企业官网建设流程全解析

Chromium 144 的 macOS 编译，最容易让人崩溃的不是后面动辄几小时的 ninja 编译，而是最前面的工具链自举。我见过太多人照着文档敲fetch chromium，结果连gclient都识别不了，或者系统里明明装了 Xcode，却一路报错找不到编译工具。这一切的源头，几乎都指向同一个环节：depot_tools有没有配好。

这是 Chromium 144 编译指南 macOS 篇的第三篇，前两篇我们把系统环境和编译前置依赖都理清了，这一篇专门解决depot_tools的安装与配置。如果你是从这一篇开始看这个系列，也没关系，我尽量把每个步骤背后的原因讲清楚，避免你只是“抄了一串命令”，却完全不知道自己在干嘛。

1. 为什么 Chromium 144 的构建绕不开 depot_tools

1.1 它到底解决什么问题

Chromium 的代码仓库不是一个普通单仓库，它上层的chromium/src只是主仓，真正构建时需要同时拉取大量第三方依赖、编译工具链、平台组件，这些依赖分散在几十个不同的代码仓库和 CIPD 包管理仓库里。你不可能手动一个一个 clone，也不可能自己维护它们之间的版本匹配关系。

depot_tools就是为了解决这个问题而存在的一套工具集。它不是一个单一的编译程序，而是包含了多个命令行工具的集合。最核心的有三个：

• gclient：负责多仓库依赖管理与版本同步，也就是 Chromium 构建里的“包管理器”角色；
• gn：负责生成 Ninja 构建文件，决定哪些源码参与编译、以什么配置编译；
• ninja：负责真正执行编译任务，利用多核并行能力把数百万行 C++ 编译成最终产物。

这三者的配合逻辑，很多人第一次接触时会绕晕。我通常用一个类比来解释：gclient像一个调度员，它把散落在各个仓库里的依赖统一拉到本地，并校验版本一致性；gn像一个设计师，根据编译目标把构建方案画成图纸；ninja才是那个施工队，按照图纸一砖一瓦地干活。

Chromium 144 这个版本对工具链的要求更苛刻，构建过程高度依赖depot_tools内部的自动更新机制。这意味着，即使你去年配好了旧版工具集，到 144 阶段也必须让depot_tools先自更新到匹配版本，否则后续gclient sync时可能因为协议变化或缓存格式不兼容而失败。

1.2 配置这件事的“正确心态”

配置depot_tools这件事，难度并不高，它不涉及编译参数调优，也不需要你理解 C++ 的复杂宏展开。但它有一个很折磨人的特点：任何一个细节出问题，错误信息都不直接。

比如gclient: command not found，表面上看是命令找不到，实际上可能是 PATH 没配好，也可能是你改完.zshrc之后没有重新加载 shell，还可能是 depot_tools 目录路径里有空格导致脚本解析出错。再比如首次运行gclient时报 Python 相关错误，很多时候不是你的系统 Python 有问题，而是 depot_tools 自带的脚本没有正确解析 Python 解释器路径。

所以这篇配置指南，我不只是把命令列出来，还会告诉你每个命令到底在做什么、哪些地方容易踩坑、报错后应该先检查哪里。

2. macOS 动手前检查清单

2.1 系统与 Xcode 环境

在配置depot_tools之前，请先确认操作系统版本。Chromium 144 的开发基线目前对 macOS 版本有明确要求，通常需要 macOS 12 或更高版本，建议使用 macOS 14 及以上，因为新版 Xcode 的行为差异会影响编译工具链。

很多人以为装个 Xcode Command Line Tools 就够了，构建 Chromium 时确实不强制要求完整 Xcode，但有几个工具是必须的：clang、ld、ar、strip、otool，这些由 Command Line Tools 提供。但要注意，完整 Xcode 的好处在于它包含了额外的 SDK 组件和模拟器运行时，如果后续调试或跑测试，少了完整 Xcode 会比较痛苦。

检查命令如下：

xcode-select -p

如果输出/Library/Developer/CommandLineTools，说明只装了命令行工具。如果输出/Applications/Xcode.app/Contents/Developer，说明完整 Xcode 已被设为当前开发者目录。

还有一个常见坑：系统升级后，Xcode 许可证协议可能需要重新接受，否则编译时会出现奇怪的权限报错。可以提前执行：

sudo xcodebuild -license accept

这里需要你输入管理员密码，输完不会有多余输出，但后续编译不会再被许可证问题卡住。

2.2 目录与磁盘

Chromium 源码目录的命名和位置非常重要。我的建议是直接放在用户目录下，也就是~/chromium或~/depot_tools，不要放在/Applications下面，也不要在路径里加入空格或中文。

为什么不能有空格？depot_tools内部有大量脚本使用 shell 字符串拼接路径，空格会直接弄断命令。例如My Documents/depot_tools这种目录，执行gclient时可能解析到My就结束了，报错信息却五花八门。

磁盘空间方面，Chromium 144 完整构建的占用非常惊人。源码拉取加依赖大概需要 30 GB 到 50 GB，编译中间产物又需要额外 60 GB 到 100 GB。这里说的不是“建议预留”，而是“必须预留”，否则在中途磁盘写满，所有编译缓存都得推倒重来。

还有一点需要注意，macOS 默认的 APFS 文件系统是大小写不敏感的，而 Chromium 官方文档推荐使用区分大小写的文件系统。因为源码里可能存在同名不同大小的文件，在大小写不敏感的文件系统上会出现文件相互覆盖的问题。如果你只有一个系统卷，不想重新格式化，可以创建一个区分大小写的专用磁盘映像，把整个 chromium 工作目录放进去。具体做法是用磁盘工具创建一个“稀疏映像”，格式选“APFS（区分大小写）”，挂载到~/chromium下。这是我实测下来比较省事的方案，既不影响系统盘，又能满足编译要求。

2.3 网络与 shell 习惯

depot_tools的安装依赖 Git 仓库克隆，这一步需要你的网络能够正常访问公开的代码托管服务，同时后续gclient sync还会从多个依赖仓库拉取大量数据。网络质量直接决定首次同步的体验，这没什么好回避的。

修改 shell 配置文件前，先确认你当前用的是 zsh 还是 bash。macOS 从 Catalina 开始默认 shell 是 zsh，但很多老教程还在教修改.bash_profile。如果你用 zsh，却把环境变量写进.bash_profile，那么新开的终端窗口永远不会加载这些配置。

你可以用下面命令确认当前 shell：

echo $SHELL

输出通常是/bin/zsh。这篇指南默认按 zsh 配置来写，如果你还在用 bash，把对应的.zshrc替换成.bash_profile即可。

3. 配置 depot_tools 的完整步骤

3.1 获取 depot_tools 源代码

配置第一步是把depot_tools克隆到本地。注意，这个仓库本身更新非常频繁，它不是一个“装完就不动”的工具。Chromium 构建系统会要求它持续跟进上游变化，因此克隆时不需要指定分支，直接用默认分支就好。

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ~/depot_tools

这一段下载量不大，通常几十 MB 就完成了。克隆完成后，先检查一下目录内容：

ls ~/depot_tools

你会看到gclient、gn、ninja等可执行文件，以及大量.py脚本。这些脚本就是 depot_tools 的“本体”，后续所有命令都会依赖它们。

克隆速度如果很慢，先排查 Git 是否配置了过大的http.postBuffer或者代理参数，这些全局配置偶尔会拖慢仓库克隆。清除干扰项之后重新克隆，通常能恢复正常的下载速度。

3.2 挂入 shell PATH

克隆完成只是第一步，关键是要让系统能找到这些命令。把depot_tools目录添加到 PATH 的最前面，让 shell 优先使用这里面的工具版本。

echo 'export PATH="$HOME/depot_tools:$PATH"' >> ~/.zshrc

这里有个细节：一定是$HOME/depot_tools:$PATH，把 depot_tools 放在前面，而不能放在后面。因为系统里可能已经存在同名的gn或ninja，如果你通过 Homebrew 装过它们，版本往往与 Chromium 要求的不一致。把 depot_tools 放在 PATH 最前面，保证优先命中正确版本。

修改完配置文件后，记得让当前终端生效：

source ~/.zshrc

然后验证：

which gclient

如果输出路径是~/depot_tools/gclient，说明配置成功。如果输出的是/usr/local/bin/gclient或早早的command not found，需要检查 PATH 是否真的被正确加载。

3.3 gclient 自检与自动更新

第一次执行gclient时，它的自更新机制会立即生效。这个过程会自动拉取 depot_tools 仓库的最新代码，并重新生成内部脚本。

gclient --version

首次运行可能耗时一到两分钟，这是正常的。你会看到类似“Updating depot_tools...”的输出，随后才显示版本信息。不要因为等待就 Ctrl+C，中途中断容易留下不完整的更新状态。如果实在中断了，重新执行一次即可，depot_tools 的更新脚本自身有恢复机制。

我还建议顺手跑一下自检命令：

gclient selfupdate

这个命令的效果等价于“拉取最新代码”，只不过目标仓库是 depot_tools 自己。自检之后，工具集基本就绪。

3.4 推荐的基础 git 配置与环境变量

在拉取 Chromium 及其依赖之前，还有几个 Git 配置建议提前设置好。特别是如果你曾经在其他平台（尤其是 Windows）上使用过 Git，行尾符设置可能残留，导致 clone 下来的源码出现 CRLF 混用，这在 C++ 编译阶段会引发大量无意义的警告。

git config --global core.autocrlf false

如果你在 macOS 的 SMB 或 NAS 上存放代码，建议追加：

git config --global core.filemode false

这样 Git 不会因为文件权限位变化而频繁标记文件为已修改，避免后续gclient sync时反复重新下载。

环境变量方面，有几个可选的配置项，但在特殊场景下很有用。比如：

export DEPOT_TOOLS_UPDATE=0 export DEPOT_TOOLS_TOOLUPDATE=0

这两个变量设成0之后，depot_tools 不会每次运行都自动更新。适合什么场景？当你在持续集成环境中需要一套固定版本的构建环境时，关闭自动更新可以保证每次构建的幂等性。但在个人开发机上，我建议保持默认开启，因为 Chromium 主仓代码更新很快，工具集不同步容易出现协议不兼容。

还有一个变量是GCLIENT_FILE，默认情况下gclient会在当前目录寻找.gclient文件。如果你需要在一个非标准目录执行同步，可以通过这个变量指向配置文件位置。这个属于进阶用法，首次配置时不用过度纠结。

4. 常见报错与排查速查表

配置depot_tools过程中，我收集了出现频率最高的几个报错。下面这个表格把症状、原因和解决方案整理到一起，遇到问题时可以直接对照。

4.1 gclient: command not found

这是最无解也是最容易解决的错误。无解在于它的诱因非常多，容易解决在于排查方向很固定。

先执行echo $PATH，看看 depot_tools 路径是否在输出列表中。如果没有，回到.zshrc文件确认配置是否正确。如果你是把配置写到了.zsh_profile但当前 shell 是 zsh，那 load 顺序会导致变量丢失。zsh 默认会加载.zshrc，而不是.zsh_profile。

另外，部分终端模拟器启动时会以 login shell 方式运行，此时会先加载.zprofile，随后加载.zshrc。如果你之前在某处写错了语法，例如少了引号，后续的 export 语句压根不会执行。建议打开配置文件看一眼：

tail -n 5 ~/.zshrc

确保最后的 export 语句没有语法错误。

4.2 首次运行 gclient 失败

首次运行gclient时，depot_tools 会尝试下载或创建一个隔离的 Python 环境。这个过程依赖 CIPD 包管理。如果你看到类似Could not find a Python interpreter或bootstrap failed的提示，优先检查系统 Python 是否可用。

macOS 自带 Python 的情况比较特殊，新系统上默认不带/usr/local/bin/python3，但会有/usr/bin/python3。如果 depot_tools 的脚本解析不到可执行解释器，可以显式指定：

export PATH="/opt/homebrew/bin:$PATH"

确保 Homebrew 安装的 Python 3 能被找到。更稳妥的做法是重新安装 Command Line Tools，因为它的安装包会顺手补齐 Python 运行时依赖：

sudo rm -rf /Library/Developer/CommandLineTools sudo xcode-select --install

这一招看起来粗暴，但确实能解决大量 Python 路径相关的问题。重装之后需要重新执行xcode-select -p验证目录存在。

4.3 Xcode 相关报错

如果你只安装了 Command Line Tools，打开 Xcode 相关命令时偶尔会收到“requires Xcode”之类的提示。这一般发生在某些脚本尝试调用只在完整 Xcode 中存在的工具时。

解决方法是手动切换开发者目录：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

切换之后再执行：

xcodebuild -version

如果能看到版本号，说明 Xcode 工具链已经可用。还有一个细节，部分脚本会读取SDKROOT环境变量，如果你之前手动设置过它，现在值指向旧 SDK，编译时会出现头文件缺失。可以取消这个环境变量：

unset SDKROOT

4.4 文件系统或磁盘问题

如果系统卷是大小写不敏感的 APFS，而你把源码放在~/chromium下，后续很可能遇到莫名其妙的编译错误：头文件找不到、符号冲突、甚至同一个文件的内容在两次读取时不同。

最干净的解决方案是创建一个区分大小写的专用映像。操作方法是在“磁盘工具”里选择“新建映像”，格式选“APFS（区分大小写）”，大小建议至少 150 GB。挂载后，把 depot_tools 和后续的源码都放在这个卷里。

磁盘空间不足时，报错往往不叫“disk full”，而是各种奇怪的写入失败。比如No space left on device出现不够直观，更多见的是编译到一半某个.o文件无法生成。建议在开始构建前用下面命令确认空间：

df -h ~ | tail -1

看到Avail列的数字小于 100 GB，就要开始考虑扩容或清理旧构建产物了。

4.5 其他高频问题

有些问题属于“配置细节没到位”。比如git config --global core.autocrlf没设置为 false，在 macOS 上本来影响不大，但如果你的 Git 配置是从其他机器复制过来的，残留的 true 设置会让同步后的源码出现大量换行符变动，进而导致后续编译时每次都会重新触发全量重编译。

还有一种情况是多用户共用一台 Mac。如果你用管理员账户执行sudo安装了很多工具，但当前编译用户不是管理员，某些缓存目录的写入权限会有问题。建议把 depot_tools 和 chromium 工作目录都放在当前用户的$HOME下，避免权限纠缠。

5. 配置完之后的若干调整与长期使用建议

5.1 PATH 顺序是个大坑

depot_tools 配置完成后，不要马上急着拉代码。先检查一下 PATH 顺序是否真的正确了。尤其是 Homebrew 用户，你的系统里很可能是存在一套独立的gn和ninja的。如果它们的位置在 depot_tools 之前，后续构建时可能会调用到错误版本，报错信息会让你误以为是代码问题。

检查顺序很容易：

which -a gn ninja

输出会按 PATH 优先级列出所有找到的路径。第一个必须是~/depot_tools/下的版本。

如果发现顺序不对，回到.zshrc检查 export 语句的位置。把 depot_tools 的 export 语句放在所有 Homebrew 相关配置之前，而不是之后。

5.2 缓存与磁盘占用

depot_tools 在执行gclient sync时会通过 CIPD 下载大量工具包和缓存。这些缓存默认存在$HOME/.cipd和$HOME/.cache下。随着时间推移，这些目录会膨胀到几 GB。

我当然不建议你手动删掉它们，因为下一次同步会重新下载，反而更慢。但如果磁盘空间已经到了“每个字节都要抠”的程度，可以谨慎清理过期的中间产物：

du -sh ~/.cipd ~/.cache/depot_tools

先看看占用量再决定动不动手。清理时只删那些明确标记为 tmp 的目录，不要动cipd的二进制索引文件夹。

5.3 关于自更新的取舍

depot_tools默认每次执行gclient都会检查自身更新。这个机制在多数时候是省心的，因为它能跟随 Chromium 主仓的演进。但如果你在某次构建中锁定了 Chromium 144 这个里程碑版本，不希望工具集随意升级到适配未来版本的形态，可以临时关闭更新：

export DEPOT_TOOLS_UPDATE=0

注意这是临时方案。等你想回到主线时，记得取消这个变量或在新的 shell 里恢复默认。我个人的习惯是写一个小脚本，里面固定好环境变量和 PATH 顺序，每次构建前source一下，避免手工敲错。

5.4 我的个人建议

配置depot_tools最忌讳的心态是“赶紧跑通，后面再说”。因为工具链自举环节的问题不会马上消失，而是会潜伏到后面的gclient sync、gn gen、甚至数小时编译过程中，再以更隐晦的方式爆发。

我在实际使用中会额外做两件事。第一件，在.zshrc里留一段清晰的注释，标明 depot_tools 的路径配置和用途。别低估这条注释的价值，三个月后你再回来看配置文件，会很庆幸当时写了这几行字。第二件，把gclient --version、gclient selfupdate这两条命令的执行结果刻意记在构建日志的开头，后面排查问题时能快速判断工具集版本是否与项目要求匹配。

还有一个容易忽视的小技巧：如果你在 IDE 里集成了终端，比如 VS Code 或 JetBrains 系列的 Terminal，它们启动时不一定加载登录 shell 的完整环境。这种情况也会导致 IDE 终端里gclient找不到。解决方法是在 IDE 设置里把终端类型改为zsh并强制加载.zshrc，或者在集成终端里手动source ~/.zshrc。

配置到这一步，depot_tools 本身已经基本就绪。下一篇我们将进入gclient sync和首次源码拉取环节，那才是真正考验耐心和磁盘空间的地方。至少现在，工具链的地基已经打好了。