yuming
ad97fd3da5
- .gitignore 新增忽略 .idea/、videos/、*.tar.gz、*.csproj.user、db 运行时文件 - 根目录 15 个中文运维 md 归档到 docs/ - 删除无部署脚本引用的 Dockerfile 与 Dockerfile-arm（保留 Dockerfile.prod） Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
395 lines
8.0 KiB
Markdown
395 lines
8.0 KiB
Markdown
# 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）
|
||
|