dysync/docs/Mac_M1_环境安装指南.md

Mac M1 芯片环境安装指南

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

---

📋 需要安装的工具

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

---

🐳 1. 安装 Docker Desktop

方法一：使用 Homebrew（推荐）

# 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 镜像）

验证安装

# 检查 Docker 版本
docker --version

# 检查 Docker 是否运行
docker ps

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

预期输出：

Docker version 24.0.x, build xxxxx

---

💻 2. 安装 .NET 6.0 SDK

方法一：使用 Homebrew（推荐）

# 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. 验证安装

# 检查 .NET 版本
dotnet --version

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

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

如果遇到问题

问题：命令未找到

# 检查 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（推荐）

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

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

预期输出：

v18.x.x 或更高版本
9.x.x 或更高版本

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

# 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. 验证安装

node --version
npm --version

安装 pnpm

方法一：使用 npm（推荐）

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

# 验证安装
pnpm --version

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

方法二：使用 Homebrew

brew install pnpm

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

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

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

source ~/.zshrc
pnpm --version

---

✅ 完整验证

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

# 检查 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

---

🚀 测试构建环境

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

# 进入项目目录
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 提示命令未找到

解决方案：

# 检查 .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 失败，提示权限错误

解决方案：

# 方法 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 下载很慢或失败

解决方案：

# 使用国内镜像源（清华大学镜像）
# 替换 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
2. 开始构建镜像：

   cd /Users/gaotu/WebstormProjects/dysync.net
   docker build -f Dockerfile.prod -t dysync.net:latest .
   

---

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