# Mac M1 芯片环境安装指南

本文档详细说明如何在 Mac M1 芯片上安装构建 dysync.net 项目所需的环境。

---

## 📋 需要安装的工具

1. **Docker Desktop** - 用于构建和运行 Docker 镜像
2. **.NET 6.0 SDK** - 用于构建后端项目
3. **Node.js 和 pnpm** - 用于构建前端项目

---

## 🐳 1. 安装 Docker Desktop

### 方法一：使用 Homebrew（推荐）

```bash
# 1. 安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 使用 Homebrew 安装 Docker Desktop
brew install --cask docker

# 3. 启动 Docker Desktop
open -a Docker
```

### 方法二：直接下载安装

1. **访问 Docker 官网**
   - 打开浏览器访问：https://www.docker.com/products/docker-desktop
   - 或直接下载：https://desktop.docker.com/mac/main/arm64/Docker.dmg

2. **安装 Docker Desktop**
   - 下载完成后，双击 `Docker.dmg` 文件
   - 将 Docker 图标拖拽到 Applications 文件夹
   - 在 Applications 中找到 Docker，双击启动

3. **首次启动配置**
   - 首次启动需要输入管理员密码
   - 等待 Docker 启动完成（状态栏会显示 Docker 图标）
   - 点击状态栏的 Docker 图标，选择 "Settings" → "General"，确保 "Use Rosetta for x86/amd64 emulation on Apple Silicon" 已勾选（如果需要运行 x86 镜像）

### 验证安装

```bash
# 检查 Docker 版本
docker --version

# 检查 Docker 是否运行
docker ps

# 如果显示容器列表（可能为空），说明安装成功
```

**预期输出**：
```
Docker version 24.0.x, build xxxxx
```

---

## 💻 2. 安装 .NET 6.0 SDK

### 方法一：使用 Homebrew（推荐）

```bash
# 1. 添加 .NET 的 Homebrew tap
brew tap isen-ng/dotnet-sdk-versions

# 2. 安装 .NET 6.0 SDK
brew install --cask dotnet-sdk6-0-400

# 3. 验证安装
dotnet --version
```

**预期输出**：`6.0.xxx`（版本号）

### 方法二：直接下载安装

1. **下载 .NET 6.0 SDK**
   - 访问：https://dotnet.microsoft.com/download/dotnet/6.0
   - 选择 "macOS" → "Arm64" → 下载安装包

2. **安装**
   - 双击下载的 `.pkg` 文件
   - 按照安装向导完成安装

3. **验证安装**

```bash
# 检查 .NET 版本
dotnet --version

# 检查已安装的 SDK
dotnet --list-sdks

# 应该看到类似输出：
# 6.0.xxx [/usr/local/share/dotnet/sdk]
```

### 如果遇到问题

**问题：命令未找到**

```bash
# 检查 PATH 环境变量
echo $PATH

# 如果 /usr/local/share/dotnet 不在 PATH 中，添加到 ~/.zshrc
echo 'export PATH="/usr/local/share/dotnet:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**问题：M1 芯片兼容性**

.NET 6.0 SDK 原生支持 Apple Silicon（M1/M2），无需特殊配置。

---

## 📦 3. 安装 Node.js 和 pnpm

### 安装 Node.js

#### 方法一：使用 Homebrew（推荐）

```bash
# 安装 Node.js（会自动安装 npm）
brew install node

# 验证安装
node --version
npm --version
```

**预期输出**：
```
v18.x.x 或更高版本
9.x.x 或更高版本
```

#### 方法二：使用 nvm（Node Version Manager，推荐用于多版本管理）

```bash
# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. 重新加载 shell 配置
source ~/.zshrc

# 3. 安装 Node.js LTS 版本
nvm install --lts

# 4. 使用最新 LTS 版本
nvm use --lts

# 5. 验证安装
node --version
npm --version
```

#### 方法三：直接下载安装

1. **访问 Node.js 官网**
   - 访问：https://nodejs.org/
   - 下载 macOS Installer（.pkg）文件
   - 选择 LTS 版本（推荐）

2. **安装**
   - 双击下载的 `.pkg` 文件
   - 按照安装向导完成安装

3. **验证安装**

```bash
node --version
npm --version
```

### 安装 pnpm

#### 方法一：使用 npm（推荐）

```bash
# 使用 npm 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version
```

**预期输出**：`8.x.x` 或更高版本

#### 方法二：使用 Homebrew

```bash
brew install pnpm
```

#### 方法三：使用独立安装脚本

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

安装完成后，重新加载 shell：

```bash
source ~/.zshrc
pnpm --version
```

---

## ✅ 完整验证

运行以下命令，确认所有工具都已正确安装：

```bash
# 检查 Docker
echo "=== Docker ==="
docker --version
docker ps

# 检查 .NET SDK
echo "=== .NET SDK ==="
dotnet --version
dotnet --list-sdks

# 检查 Node.js
echo "=== Node.js ==="
node --version
npm --version

# 检查 pnpm
echo "=== pnpm ==="
pnpm --version
```

**预期输出示例**：
```
=== Docker ===
Docker version 24.0.6, build ed223bc
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

=== .NET SDK ===
6.0.425
6.0.425 [/usr/local/share/dotnet/sdk]

=== Node.js ===
v18.17.0
9.6.7

=== pnpm ===
8.15.0
```

---

## 🚀 测试构建环境

安装完成后，可以测试构建环境是否正常工作：

```bash
# 进入项目目录
cd /Users/gaotu/WebstormProjects/dysync.net

# 测试 Docker 构建（可选，会花费一些时间）
# docker build -f Dockerfile.prod -t dysync.net:test .

# 测试 .NET 项目构建
cd /Users/gaotu/WebstormProjects/dysync.net
dotnet restore
dotnet build

# 测试前端构建
cd /Users/gaotu/WebstormProjects/dysync.net/app
pnpm install
pnpm build
```

---

## 🐛 常见问题

### 问题 1：Docker Desktop 无法启动

**症状**：点击 Docker Desktop 后没有反应或报错

**解决方案**：
1. 检查系统要求：macOS 11.0 或更高版本
2. 重启 Mac
3. 检查是否有其他虚拟化软件冲突（如 VirtualBox）
4. 重新安装 Docker Desktop

### 问题 2：.NET SDK 命令未找到

**症状**：执行 `dotnet --version` 提示命令未找到

**解决方案**：

```bash
# 检查 .NET 安装位置
ls -la /usr/local/share/dotnet

# 如果不存在，检查其他可能的位置
which dotnet

# 添加到 PATH（如果使用 zsh）
echo 'export PATH="/usr/local/share/dotnet:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 如果使用 bash
echo 'export PATH="/usr/local/share/dotnet:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
```

### 问题 3：pnpm 安装失败

**症状**：`npm install -g pnpm` 失败，提示权限错误

**解决方案**：

```bash
# 方法 1：使用 sudo（不推荐）
sudo npm install -g pnpm

# 方法 2：配置 npm 使用其他目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g pnpm

# 方法 3：使用 Homebrew
brew install pnpm
```

### 问题 4：M1 芯片兼容性问题

**症状**：某些工具在 M1 上运行异常

**解决方案**：
- **Docker Desktop**：确保使用 Apple Silicon 版本（arm64）
- **.NET SDK**：.NET 6.0 原生支持 M1，无需特殊配置
- **Node.js**：使用 nvm 安装时，会自动选择 arm64 版本

### 问题 5：Homebrew 安装慢或失败

**症状**：`brew install` 下载很慢或失败

**解决方案**：

```bash
# 使用国内镜像源（清华大学镜像）
# 替换 Homebrew 源
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"

# 或使用中科大镜像
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
```

---

## 📚 参考资源

- **Docker Desktop for Mac**：https://docs.docker.com/desktop/install/mac-install/
- **.NET 6.0 下载**：https://dotnet.microsoft.com/download/dotnet/6.0
- **Node.js 下载**：https://nodejs.org/
- **pnpm 文档**：https://pnpm.io/installation

---

## 🎯 下一步

安装完成后，可以开始构建项目：

1. **查看构建指南**：[飞牛NAS详细部署方案.md](./飞牛NAS详细部署方案.md)
2. **开始构建镜像**：
   ```bash
   cd /Users/gaotu/WebstormProjects/dysync.net
   docker build -f Dockerfile.prod -t dysync.net:latest .
   ```

---

**最后更新**：2024-11-22  
**适用系统**：macOS（Apple Silicon M1/M2）