适用对象：在 macOS 13 或更高版本上完成 DSA Mastery 本地 C++ Lab 的学生，支持 Apple Silicon 与 Intel Mac。
0. 原生自举安装（推荐）
如果你希望一次完成工具检查、仓库准备、依赖安装和第一个 Lab 验证，直接运行仓库自带的 macOS 启动器即可。启动器会检查并按需准备 Git、Node.js、pnpm、Apple Clang、CMake、仓库依赖和 VS Code；不需要预先安装 Node.js，支持 Apple Silicon 与 Intel Mac。
已经有仓库
在终端直接粘贴下面两行：
cd ~/code/DSA-Mastery
bash scripts/bootstrap/bootstrap-macos.sh如果仓库在其他位置，只需要把第一行换成实际目录，例如 cd ~/DSA-Mastery。
还没有仓库
如果 Git 和仓库都还没有准备好，先下载启动器，再由它准备工具并 clone 仓库：
curl -fL https://raw.githubusercontent.com/AzenAnn/DSA-Mastery/main/scripts/bootstrap/bootstrap-macos.sh -o /tmp/bootstrap-macos.sh
bash /tmp/bootstrap-macos.sh --repo-dir "$HOME/code/DSA-Mastery"如果你已经可以使用 Git，也可以先 clone，再回到上面的“已经有仓库”路径：
mkdir -p ~/code
git clone https://github.com/AzenAnn/DSA-Mastery.git ~/code/DSA-Mastery
cd ~/code/DSA-Mastery
bash scripts/bootstrap/bootstrap-macos.sh不带参数运行时会进入交互式选择界面：
# ↑↓ 或 j/k：移动；空格：选择/取消；Enter：开始；q：退出基础运行环境（Git、Node.js、pnpm）是必选项。默认会选择 Program Lab C++ 环境；如果需要 Project Lab，就勾选 Project Lab / CMake；需要图形界面时再勾选 VS Code 和相应扩展。脚本会自动勾选扩展依赖，并根据选择执行对应的环境检查。
菜单中的方案对应：runtime（只准备课程工具）、basic（Program）和 full（Program + Project）。
熟悉命令行后，也可以直接指定方案：
# 只安装并验证 Quiz/Program 所需环境
bash scripts/bootstrap/bootstrap-macos.sh --profile basic
# 完整课程环境，额外安装并验证 CMake/Project Lab
bash scripts/bootstrap/bootstrap-macos.sh --profile full常用选项：
# 只读检查，不安装工具、不 clone/pull、不安装依赖、不运行 smoke
bash scripts/bootstrap/bootstrap-macos.sh --check-only --profile basic --repo-dir "/Users/me/课程项目/DSA-Mastery"
# 跳过 VS Code；脚本默认不会强制安装 IDE
bash scripts/bootstrap/bootstrap-macos.sh --profile full --skip-vscode
# CI 或重定向时使用稳定纯文本/JSON 输出
bash scripts/bootstrap/bootstrap-macos.sh --profile basic --non-interactive --ui plain
bash scripts/bootstrap/bootstrap-macos.sh --profile basic --non-interactive --jsonTTY 中会显示阶段面板、状态、进度和失败摘要；成功时会显示完成信息，支持颜色的终端还会显示像素风完成 Banner。非 TTY 会自动降级为纯文本。安装失败后直接重跑同一命令即可，已满足的工具和依赖会被复用。核心失败日志写入 ~/Library/Logs/DSA-Mastery/setup/；--check-only 不创建日志。
脚本可能打开 Homebrew 或 Xcode Command Line Tools 系统安装流程。遇到密码、系统弹窗、网络代理或设备管理限制时，按提示完成操作后重新运行；脚本不会绕过 macOS 权限，也不会覆盖仓库中的未提交改动。
如果设备不允许 Homebrew 或远程下载，请跳到下面的手工安装章节。手工路径与脚本使用相同版本要求；Node.js 没有 Corepack 时，脚本会回退到 npm 安装固定版本 pnpm 11.1.1。
开始前，可以点击屏幕左上角的 Apple 菜单，选择“关于本机”，确认 macOS 版本和芯片类型。显示“Apple M1/M2/M3/M4”等型号时选择 Apple Silicon（ARM64）安装包；显示 Intel 时选择 x64 安装包。
1. 安装 Xcode Command Line Tools
DSA Mastery 的 C++ Lab 需要 Git、C++ 编译器和 Make。macOS 可以通过 Xcode Command Line Tools 安装这些基础工具，无需下载完整的 Xcode。
打开终端，执行：
xcode-select --install在弹出的窗口中点击“安装”，同意许可协议并等待安装完成。如果提示工具已经安装，则无需重复安装。
安装完成后，在终端运行：
echo "=== Xcode Command Line Tools 安装检查 ==="
echo
echo "开发工具路径："
xcode-select -p
echo
echo "Git 版本："
git --version
echo
echo "C++ 编译器版本："
clang++ --version | head -n 3xcode-select -p 通常会输出以下路径之一：
/Library/Developer/CommandLineTools或者：
/Applications/Xcode.app/Contents/Developer能够正常显示开发工具路径、Git 版本和 Apple Clang 版本，即表示安装成功。
Apple 官方说明：安装 Xcode Command Line Tools
2. （可选）安装 Homebrew
Homebrew 是 macOS 常用的软件包管理工具，方便后续安装其他开发工具。本指南中的 Node.js 和 CMake 均使用官方图形安装包，因此不安装 Homebrew 也可以完成课程 Lab。
2.1 下载安装包
打开 Homebrew 最新版本页面，展开页面底部的 Assets，点击 Homebrew.pkg。
不要下载 Source code 文件。
下载完成后，双击 Homebrew.pkg 打开安装器。
2.2 完成安装
进入安装器后，点击“继续”。
阅读软件许可协议，然后点击“继续”。
在弹出的确认窗口中点击“同意”。
保持默认安装位置，点击“安装”。系统可能要求输入 Mac 登录密码或使用 Touch ID。
出现“安装成功”后，点击“关闭”。
2.3 配置终端环境
安装完成后，需要将 Homebrew 加入终端环境。
Apple Silicon Mac 执行：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"Intel Mac 执行：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"最后检查安装结果：
brew --version
brew --prefix可以得到如下：
Apple Silicon Mac 的安装路径通常为 /opt/homebrew，Intel Mac 通常为 /usr/local。能够正常显示版本和安装路径，即表示 Homebrew 已可使用。
Homebrew 官方安装说明：Homebrew Installation
Homebrew 官方网站：Homebrew
3. 安装 Node.js 和 pnpm
本指南推荐安装 Node.js 24 LTS。不要使用 npm 替代 pnpm 安装项目依赖，否则可能产生与仓库不一致的锁文件。
3.1 下载 Node.js
打开 Node.js 官方下载页面，选择：
- 版本：Node.js 24 LTS
- 系统：macOS
- Apple Silicon Mac：
ARM64 - Intel Mac：
x64
然后点击 macOS Installer (.pkg)。
3.2 安装 Node.js
双击下载的 .pkg 文件，打开 Node.js 安装器。
点击“继续”，按照提示阅读并同意许可协议，然后保持默认安装位置完成安装。系统可能要求输入 Mac 登录密码或使用 Touch ID。
安装完成后，关闭并重新打开终端。
3.3 检查 Node.js
在终端运行：
node --version
npm --version
corepack --version
which nodeNode.js 应显示 v24.x.x，安装路径通常为：
/usr/local/bin/node
3.4 安装 pnpm
Node.js 24 附带 Corepack，可以通过 Corepack 安装项目指定的 pnpm。
使用官方 .pkg 安装 Node.js 时，Corepack 需要管理员权限在 /usr/local/bin 中创建 pnpm 命令。执行：
sudo corepack enable pnpm终端会要求输入 Mac 登录密码。输入密码时不会显示字符，正常输入并按回车即可。
然后安装并固定 pnpm 版本：
corepack install --global pnpm@11.1.1
hash -r检查安装结果：
pnpm --version
which pnpm预期版本为：
11.1.1安装路径通常为：
/usr/local/bin/pnpm
至此，Node.js 和 pnpm 均已安装完成。
4. 安装 VS Code
Visual Studio Code 用于编辑代码和查看项目文件。它本身不包含 C++ 编译器；前面安装的 Apple Clang 负责编译 C++ 程序。
4.1 下载 VS Code
打开 VS Code 官方下载页面，选择适合当前 Mac 的安装包。
4.2 安装 C++ 扩展
打开 VS Code 左侧的“扩展”页面，搜索并安装：
C/C++确认扩展发布者为 Microsoft，扩展 ID 为：
ms-vscode.cpptools该扩展提供 C++ 代码补全、语法检查和调试支持。
如果后续需要运行或调试 CMake Project Lab，还可以安装 CMake Tools，扩展 ID 为 ms-vscode.cmake-tools。
4.3 启用 code 命令
按 Command + Shift + P 打开命令面板，搜索并执行：
Shell Command: Install 'code' command in PATH关闭并重新打开终端，然后检查：
code --version之后可以在项目目录中执行：
code .用 VS Code 打开整个项目。
5. 安装 CMake
Project Lab 需要 CMake。打开 CMake 官方下载页面，下载：
cmake-4.4.3-macos-universal.dmg
打开 .dmg 文件，将 CMake.app 拖入 Applications 文件夹。
然后在终端执行：
sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install重新打开终端并检查：
cmake --version
which cmakeCMake 版本为 3.25 或更高即表示安装成功。
6. 验证完整环境
打开终端，依次执行：
echo "Git 版本："
git --version
echo
echo "Node.js 版本："
node --version
echo
echo "pnpm 版本："
pnpm --version
echo
echo "C++ 编译器版本："
clang++ --version | head -n 3
echo
echo "CMake 版本："
cmake --version | head -n 1版本要求：
| 工具 | 要求 |
|---|---|
| Node.js | 22.13.0 或更高 |
| pnpm | 11.1.1 |
| Apple Clang | 14.0.0 或更高 |
| CMake | 3.25 或更高 |
能够正常显示各工具的版本号，即表示环境安装完成。
7. 下载课程仓库
建议把代码放在路径简短、没有特殊符号的目录中，例如 ~/Projects。打开终端，执行：
mkdir -p ~/Projects
cd ~/Projects
git clone https://github.com/AzenAnn/DSA-Mastery.git
cd DSA-Mastery
pnpm install --frozen-lockfile第一次安装依赖需要联网。出现 Done 且没有错误信息，即表示依赖安装成功。
如果已经 Fork 了仓库，并且需要向自己的仓库提交修改，请把克隆地址替换为自己的地址，例如：
git clone https://github.com/yourid/DSA-Mastery.git也可以从 GitHub 下载 ZIP，但 ZIP 不包含完整的 Git 历史，不方便同步更新和提交 PR，因此推荐使用 git clone。
安装完成后，可以在仓库目录执行：
code .8. 运行第一个 Program Lab
进入仓库根目录：
cd ~/Projects/DSA-Mastery先检查运行环境：
pnpm lab:doctor -- labs/chapter-01/exercise/E-01-01-sequential-list-deduplication看到 PASS 环境检查，并且 Clang 显示 AVAILABLE，即可继续。
为了确认编译和测试流程正常，可以运行仓库中的参考实现：
pnpm lab:run -- labs/chapter-01/exercise/E-01-01-sequential-list-deduplication --target solution看到 PASS、4/4 cases 和 100/100，表示测试全部通过。
也可以只运行示例测试：
pnpm lab:run -- labs/chapter-01/exercise/E-01-01-sequential-list-deduplication --target solution --case 001-sample
--target solution 用于验证仓库提供的参考实现。学生完成自己的代码后，应去掉该参数：
pnpm lab:run -- labs/chapter-01/exercise/E-01-01-sequential-list-deduplication9. 运行 Project Lab
Project Lab 需要 Apple Clang 和 CMake。先执行环境检查：
pnpm lab:doctor -- labs/chapter-08/project/P-08-01-avl-tree-rotations看到 PASS 环境检查，并且 Clang 和 CMake 显示 AVAILABLE，即可继续。MSVC 仅供 Windows 使用，显示 NOT FOUND 属于正常情况；GNU Make 版本较旧也不影响使用 pnpm。
运行 Project Lab 的参考实现：
pnpm lab:run -- labs/chapter-08/project/P-08-01-avl-tree-rotations --target solution自动测试通过后会显示：
AUTOMATED PASS · MANUAL REVIEW PENDING其中 PENDING 表示报告部分需要人工评分，不代表运行失败。
也可以只运行指定任务和测试用例：
pnpm lab:run -- labs/chapter-08/project/P-08-01-avl-tree-rotations --target solution --task bst --case 001-basic看到 AUTOMATED PASS 即表示该测试通过。因为这里只运行了一个任务，所以 Provisional total 不会显示为 100 分。
学生完成自己的 Project 代码后，应去掉 --target solution，测试 student 目录中的实现。