圣狗子在 macOS 上从源码编译 Chromium 144，第一件事不是急着敲编译命令，而是把环境准备做扎实。Chromium 的编译流程和普通开源项目完全不一样：它下层是一整套 depot_tools 工具链，依赖超过 20 个外部仓库，整个项目下载量动辄几十 GB，构建产物又是几十 GB。稍微少配置一样东西，后边都可能卡上几小时。这篇“环境准备（一）”专门解决从零到能跑通 autoninja -C out/Default chrome 之前的全部环节，适合三种人：想定制或学习浏览器源码的开发者、需要做自动化测试或内核研究的同学，以及单纯想验证“我在 macOS 上能不能自己造一个浏览器”的折腾派。
我直接把这些年踩过的坑揉进步骤里。你照着做，大概率能一次通，不用像我当年那样对着报错日志翻半天。
1. 编译前的硬性账目：硬件、系统和网络
1.1 硬件门槛：内存、硬盘与 CPU 的真实预算
先说硬盘。很多人对这个项目的体积没有概念——它不是一个 XXL 的仓库，是一整个“仓库群”。源码本身在拉取完依赖之后通常要占 20GB 到 40GB，取决于你有没有带完整 Git 历史；编译产物又会在 out 目录里堆出几十 GB。我个人的建议是最少预留 150GB 空闲磁盘，如果打算同时保留 Debug 和 Release 两套构建目录，那就按 250GB 以上算。别小看这一步，我见过好几个朋友编译到一半发现磁盘见底，最后只能删掉重来。
内存是另一个隐藏瓶颈。编译时 ninja 会按照核数并行开任务，每个编译进程都要吃几百 MB 内存，最后的链接阶段 lld 更是吃内存大户。16GB 是底线，但如果你用的是 8 核以上的机器，16GB 很容易在链接时被系统杀掉进程。我自己的感受是 32GB 才算舒服，Apple Silicon 的统一内存架构在这方面优势很明显。
CPU 方面，Apple Silicon 的编译速度比同代 Intel Mac 快出好几倍。M1 芯片完整编译一次 Release 版 Chromium 大约 2 到 3 小时，M2/M3 会更快；老款 Intel Mac 可能要跑一整晚。如果你用的是 Intel 机型，后面我会讲怎么手动限制并行数，避免把机器跑死。
1.2 macOS 系统版本与 Xcode 的版本对应关系
Chromium 官方对系统版本和 Xcode 版本的匹配要求很严格。以 Chromium 144 这个时间节点来看，macOS 12 以下基本不要想了，建议直接用当前最新稳定版 macOS，比如 macOS 15 Sequoia。为什么这么强调版本？因为 Chromium 的构建脚本会调用系统 SDK 里的头文件和链接库，SDK 太旧，编译到某个底层模块时就会冒出一堆“symbol not found”或者“unknown argument”之类的报错。
Xcode 也一样，最好是当前最新的稳定大版本，也就是 Xcode 16.x 这一代。这里有个细节：Chromium 官方 CI 每天跑的都是新系统新工具链，你用落后两个大版本的工具链去编译，遇到问题基本只能自己扛，官方文档不会管你。
如果你机器上同时装了几个版本的 Xcode，可以用下面命令切换：
bash复制sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p
第二条命令输出为 /Applications/Xcode.app/Contents/Developer 就说明切换成功。这个切换操作在跨系统升级后特别常用，Xcode 路径一旦乱掉，后面所有构建脚本都会找不到编译器。
1.3 网络与下载：这是一个“几十 GB 级”的拉取任务
Chromium 源码托管在多个 Git 仓库里，主仓库之外的第三方库都靠 DEPS 文件声明版本，然后由 gclient 逐个拉取。整个 fetch 加 sync 过程下载量通常在 20GB 以上，这还没算编译工具链的下载。所以网络环境比“快”更重要的是“稳定”。
我最推荐的姿势是插网线，或者找一个信号强的固定位置，避免下载到一半 Wi-Fi 切换导致连接重置。gclient sync 虽然支持断点续传，但有些 zip 包下载中断后会从头再来，反复几次心态真的会崩。另外，同时开一大堆下载任务抢带宽这种事千万别干——我见过有人一边下源码一边挂游戏更新器，结果几十个依赖仓库轮流超时。
如果你连接官方代码托管源确实不太顺，可以适当重试几次，或者在网络空闲时段再跑。有人会去修改 depot_tools 里的默认源地址，这个方法确实能解决一部分网络问题，但新手我不建议动，因为不同源之间的版本同步节奏不一样，改不好会让依赖版本对不上，排查起来比网络问题更痛苦。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 基础环境安装：Xcode、编译器与 Python
2.1 不要只装命令行工具，要装完整版 Xcode
这句话我要放到最前面：Chromium 编译需要的是完整版 Xcode，不是 xcode-select --install 装的那个 CommandLineTools。很多新手在这里栽跟头，觉得既然只是编译，命令行工具就够了。实际上 Chromium 的构建脚本会直接去 /Applications/Xcode.app 找 SDK，命令行工具里没有完整的 macOS SDK，更没有 Xcode 自带的编译器套件。
正确做法是打开 App Store，搜索 Xcode，直接下载安装。Xcode 安装包体积很大，需要耐心等。安装完成后先确认三件事：
bash复制xcode-select -p
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
第一条看当前激活的开发者目录，第二条把 Xcode 路径指正，第三条接受许可证。许可证不接受的典型症状是编译到一半突然报 Agreeing to the Xcode license ... 然后中断，别问我怎么知道的，这是每个 macOS 编译者都绕不开的一课。
2.2 macOS 自带的 Python 够用吗？
够用，而且建议优先用系统自带的 Python 3。Chromium 的构建脚本是 Python 写的，对版本有一定要求，macOS 自带的 /usr/bin/python3 版本足够满足。我知道很多人习惯用 Homebrew 装新版本 Python，也不是不行，但要注意别让 shell 里默认的 Python 版本太激进，比如 3.13 在某些脚本上可能会触发兼容性警告。
一个小建议：检查一下当前 Python 和 Git 版本：
bash复制python3 --version
git --version
只要 python3 能正常输出且不低于 3.9，Git 能输出版本号，就说明基础环境没问题。这两个工具出错的话，后边的 gclient 根本跑不起来。
2.3 Git 配置、中文路径与目录权限的三个提前量
Xcode 完整安装后自带 Git，不需要额外装。但有两个 Git 配置必须提前做：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
Chromium 的很多脚本会读取提交者信息，尤其是你准备在源码上做修改、提交 patch 的时候，这两项缺失会直接报错。别问为什么只是编译还要配这个，项目就是这么设计的。
目录路径问题容易被忽略。Chromium 对路径里的空格、非 ASCII 字符很敏感，如果你的用户名是中文，或者路径里带了空格，某些脚本在解析路径时会行为怪异。稳妥的做法是把源码放在纯英文路径下，比如 /Users/Shared/chromium-dev 或者 /opt/chromium-dev。放在 /Users/Shared 下还有额外好处：不同用户都能访问，权限问题少。
还有目录权限，最好不要把源码放到系统没有写权限的目录，否则后面 gclient sync 生成文件时会持续报 Operation not permitted，检查起来非常头疼。
3. 搭建 depot_tools 工具链并拉取源码
3.1 depot_tools 是什么，为什么不用普通 git clone？
如果你尝试过直接 git clone Chromium 仓库，会发现它只有主仓库，真正编的时候缺一堆第三方代码。这是因为 Chromium 把依赖管理做成了一个“多仓库 + 版本对齐”的系统：顶层有个 DEPS 文件，里面声明了每一个外部依赖仓库应该 checkout 到哪个 commit，gclient 就负责按这个文件把所有东西拉齐。
depot_tools 就是这个体系的核心工具集，里面包含 gclient、gn、ninja、autoninja 等命令。安装它非常简单：
bash复制mkdir -p ~/chromium-dev && cd ~/chromium-dev
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
echo 'export PATH="$PATH:$HOME/chromium-dev/depot_tools"' >> ~/.zshrc
source ~/.zshrc
用 zsh 的话就写进 .zshrc，用 bash 就写进 .bash_profile。验证一下：
bash复制which fetch
which gclient
能输出路径就表示工具链就位。fetch 是高层封装命令，负责初始化整个 Chromium 目录结构；gclient 负责同步依赖；gn 负责生成构建文件；autoninja 负责并行编译。
3.2 拉取源码：fetch 与 gclient sync 的关系
进入源码目录，执行：
bash复制cd ~/chromium-dev
fetch --nohooks chromium
这里用 --nohooks 的意思是暂时不跑下载钩子，先把核心源码拉下来。钩子是什么？简单说就是 DEPS 文件里附带的一些下载任务，比如预编译好的 clang 编译器、一些二进制工具等。这些内容体积很大，放到后面单独处理，可以让 fetch 阶段更快跑完。
如果你不是特别需要完整 Git 历史，可以加一个参数：
bash复制fetch --no-history --nohooks chromium
--no-history 会把仓库变成浅克隆，拉取量减少非常多，第一次上手编译强烈推荐。缺点是以后想用 git log 看提交历史会信息不全，但环境准备阶段这点代价可以接受。
fetch 完成后会生成 src/ 目录，接下来进入源码目录同步依赖：
bash复制cd src
gclient sync
这一步会读取 DEPS，把几十个第三方仓库挨个拉取到对应版本。第一次跑非常耗时，经常一两个小时起步。失败也不用慌，重新执行同一条命令就会继续未完成的部分。我的经验是，如果连续失败三次以上，先别急着重试，检查一下是不是网络整体出问题了。
3.3 用 hooks 下载编译工具链
刚才 fetch 用了 --nohooks，所以现在要手动补齐：
bash复制gclient runhooks
这个命令会去下载 Chromium 自己维护的 clang 编译器、sysroot 依赖等大件。macOS 上本质上还是走系统 Xcode 的 SDK，但 Chromium 也会下载一部分它自己定制的工具链，体积几个 GB。这一步网络要求同样很高，如果失败了就重跑，和 gclient sync 一样的套路。
跑完 runhooks，环境准备阶段就基本完工了。你现在手里已经有一套完整、可编译的 Chromium 源码树，接下来就是生成构建文件和真正开编。
4. 用 gn 生成构建文件并启动首次编译
4.1 gn 与构建参数的选择逻辑
Chromium 的构建系统是两层架构：gn 生成 ninja 文件，ninja 负责真正的编译。每次修改构建参数，都要重新运行 gn。先创建输出目录：
bash复制cd src
gn gen out/Default --args="is_debug=false is_component_build=true symbol_level=1"
这三个参数是我给大部分人的起步配置。is_debug=false 表示编译 Release 版，运行效率高很多；is_component_build=true 会把各个模块编译成动态库，链接速度快一个数量级，这对日常迭代是最关键的；symbol_level=1 表示保留基本调试符号但裁剪掉冗余调试信息，编译时间和磁盘占用都能少一大截。
如果你想更接近官方正式版配置，可以用：
bash复制gn gen out/Official --args="is_official_build=true is_debug=false symbol_level=1"
is_official_build=true 会开启官方发布级别的优化，比如针对 Chrome 的专用优化参数、关闭一些试验字段。但代价是编译时间明显变长，而且对新手不算友好，我建议第一次先别用。
常用构建参数对比如下：
| 参数 | 常用值 | 作用 | 我的建议 |
|---|---|---|---|
| is_debug | true/false | 是否为调试版 | 日常编译用 false，真需要断点调试再开 true |
| is_component_build | true/false | 是否编译为动态库形态 | 开发首选 true，追求最终产物完整性用 false |
| symbol_level | 0/1/2 | 调试符号精度 | 1 是平衡点，0 更省但排错困难 |
| is_official_build | true/false | 是否按官方发布标准构建 | 第一次别开 |
| enable_nacl | true/false | 是否编译 NaCl 模块 | 现在基本已经移除，不用管 |
Apple Silicon 用户不用特意指定 target_cpu，gn 会自动读取主机架构生成 arm64 构建。Intel Mac 想交叉编译 arm64 也不是不行，但没必要给自己添堵。
4.2 正式编译：autoninja 的使用与并发控制
构建文件生成好之后，执行：
bash复制cd src
autoninja -C out/Default chrome
autoninja 会自动根据 CPU 核数和内存调整并行任务数。默认策略其实已经很保守了，但如果你内存确实比较小，可能会出现编译进程被系统杀掉的情况。症状就是终端里突然一堆 Killed 或者 signal 9，这时候手动限制并行数：
bash复制autoninja -C out/Default chrome -j 4
-j 参数指定同时编译的任务数。4 个任务基本是保底配置，虽然慢，但是稳定。
首次编译时间：M 系列芯片上 Release + component build 大约 1.5 到 3 小时；Intel 老机器可能 6 小时以上。你想快速验证环境是否完整，可以先编一个轻量目标：
bash复制autoninja -C out/Default content_shell
content_shell 是一个简化版浏览器外壳，比完整版 Chromium 小很多，编译时间能缩短一半以上。用它来验证“我的环境到底通没通”非常合适，通了再回去编完整 chrome 也不迟。
4.3 首次运行与后续迭代
编译完成后，产物目录是 out/Default。完整版产物通常在 out/Default/Chromium.app，直接双击运行，或者命令行启动：
bash复制open out/Default/Chromium.app
想带参数调试的时候，可以执行二进制：
bash复制./out/Default/Chromium.app/Contents/MacOS/Chromium --no-first-run
注意，像 --no-sandbox 这种参数只在特定自动化测试场景下用，日常使用我强烈不建议关沙箱，安全没必要赌。
后续想更新代码，标准流程是：
bash复制git fetch origin
git checkout origin/main
gclient sync -D
autoninja -C out/Default chrome
gclient sync -D 里的 -D 会把已经不用的依赖目录删掉，避免旧文件残留影响构建。增量编译会比首次快很多，改了代码之后通常几分钟到十几分钟就能出新产物。
5. 常见问题排查与实操避坑
5.1 几个高频报错的快速定位表
我在多次编译中总结出来一张速查表，第一次编译遇到问题先来这里对号入座：
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| xcode-select: error: tool 'xcodebuild' requires Xcode | 只装了命令行工具 | 装完整 Xcode 并执行 xcode-select -s |
| You have not agreed to the Xcode license agreements | Xcode 许可证未接受 | sudo xcodebuild -license accept |
| Failed to fetch / connection timed out | 网络不稳定 | 重跑 gclient sync，错开高峰时段 |
| Operation not permitted | 目录权限不够 | 把源码放到 /Users/Shared 下或调整目录权限 |
| autoninja 进程被 Killed | 内存不足 | 降低 -j 并发数，关闭不吃内存的后台应用 |
| clang: error: unable to execute command: Segmentation fault | 编译进程内存不够或机器过热 | 清理后台任务，减少并行度 |
| git: 'remote-https' is not a git command | Git 安装异常 | 确认 /usr/bin/git 存在，重装 Xcode 命令行工具 |
5.2 网络下载中断怎么办？
这是每个人几乎一定会碰到的问题。Chromium 的第三方依赖来自多个外部仓库，gclient sync 有断点续传设计，但某些 zip 包下载中断后要重来。我的经验是把“失败后重跑”当成正常操作，不要一失败就焦虑。
连续失败超过三次，先检查整体网络，再看看是不是磁盘满了。如果一直卡在 gclient sync 的同一位置，可以用 gclient sync --shallow 或者 --no-history 减少单次下载量。这些参数在环境准备阶段能显著降低网络依赖，如果后续做源码研究需要完整历史，再把历史补回来也不难。
5.3 想切到稳定版分支而不是 main
Chromium 的 main 分支对应的是未来版本，说实话并不适合初学者。我更推荐锁定到特定版本分支上。比如要基于 Chromium 144 编译，可以这样：
bash复制git -C src fetch --tags origin
git -C src checkout 144.0.xxxx.x
或者直接基于分支建立工作分支：
bash复制git -C src checkout -b mybuild origin/144
使用分支的好处是它会持续接收该版本线的修复更新，配合：
bash复制gclient sync --with_branch_heads
可以一次性把所有分支引用信息都拉下来，之后切分支就不用再 fetch 了。新手开局就锁定分支，能少踩很多“main 分支今天改、明天改、后天编译再次报错”的坑。
5.4 编译到一半磁盘满了，怎么救？
先看占用情况：
bash复制du -sh ~/chromium-dev
du -sh ~/chromium-dev/src/out
最直接的清理手段是删掉输出目录重新生成：rm -rf out/Default。听起来粗暴，但有时候比各种技巧都好使。如果不想全删，可以在 gn args 里调低 symbol_level，或者把 is_component_build 改成 true，然后重新生成一遍构建文件，增量编译会只重新编译受影响的模块，磁盘占用会小很多。
另一个容易忽略的是 macOS 的“本地快照”。时间机器如果配置了本地快照，会悄悄占掉大量空间。在“系统设置 → 通用 → 存储空间”里看一眼，必要的时候清理掉开发者缓存。
5.5 经验补充：如何让每次增量编译更快
环境搭建好之后，后续迭代速度才是真正影响效率的点。我自己的习惯是固定用 is_component_build=true 加上 symbol_level=1，这两项能让链接时间缩短一个数量级。Debug 符号和静态库形态虽然更接近最终发布版，但每次改一行代码要等十分钟链接，那个感受真的不好。
另外，尽量保持同一个输出目录长期使用。gn 的增量缓存挂在输出目录里，频繁 rm -rf out/Default 再重建，等于不断全量重编。如果你确实需要两套配置，比如一套 Release 用来跑测试、一套 Debug 用来追代码，那就把输出目录分开命名，out/Release 和 out/Debug 各管各的，互相不干扰。
还有一个小技巧：在 src 目录里创建一个 .gn 文件旁边的 args.gn 模板，把常用参数写进去，下次新建构建目录时直接复制，不用每次敲一长串参数。我就是靠这个方法，在新机器上从零到跑通首次编译，比第一次少花了一个多小时。