上周一位读者私信我说照着网上某篇教程在 macOS 上编译 Chromium折腾了整整三天连环境都没搭起来。我远程帮他看了一眼三个坑全部踩中装的是 Xcode beta 版、depot_tools 用的是 Homebrew 版本、磁盘分区只剩不到 60GB。这三个问题官方文档里其实都写清楚了但分散在不同的页面第一次接触的人很难把它们串成一条完整链路。这也正是我想写这一系列 macOS 编译指南的原因。这篇是 Chromium 144 编译指南 macOS 篇的第一篇只聚焦一件事把编译环境完整、稳妥地准备好。Chromium 的版本号跟着 Chrome 走144 这个数字对应的是 Chrome 144 的时间线代码里src/chrome/VERSION会明确写着MAJOR144。这个里程碑算是比较新的主线版本生态和社区资料都比较齐全拿来当学习目标或开发基线都合适。适合谁看正在从零开始编译 Chromium 但被环境劝退的开发者准备把 Chromium 源码作为研究对象但不知道从哪下手的同学以及想在 M 系列芯片的 Mac 上搭一套可复用开发环境的人。1. 硬性门槛编译 Chromium 144 之前先看看这台 Mac 合不合格很多人拿到新 Mac 的第一反应是赶紧装个 Xcode 就开搞其实编译 Chromium 对硬件和系统版本的要求比想象中高得多。与其到编译中途被各种诡异报错打断不如在最开始就把这台机器的底细摸清楚。1.1 内存和 CPU16GB 是下限32GB 才谈得上从容Chromium 是一个体量极其夸张的 C 项目模板实例化的密集程度在业界数一数二。编译过程中 clang 会开多个并行进程同时编译不同目标文件每个 clang 进程动辄吃掉 1-2GB 内存。到了链接阶段更夸张ld64 需要把几千个 .o 文件一次性加载进内存做符号解析和重定位内存占用会瞬间飙到 10GB 以上。我自己的实测感受是8GB 内存的机器可以直接放弃连拉源码都费劲16GB 能编译但并发数得手动限制否则系统会频繁触发内存压缩整机卡到鼠标都在飘32GB 以上才是真正舒服的起点Ninja 默认并发基本不会撞到内存天花板。Apple Silicon 的 Mac 因为采用统一内存架构内存同时还被 GPU 占用日常开几个浏览器标签页加 IDE再跑编译压力会比同容量 Intel 机型更明显。先执行下面的命令确认一下当前机器的基本盘sysctl -n hw.memsize # 内存大小单位字节 sysctl -n hw.ncpu # CPU 核心数 uname -m # 输出 arm64 或 x86_64从实践角度讲内存和 CPU 核心数决定了后续构建时的并发参数怎么设置。核心数多但内存小的话autoninja默认的并发数反而可能把机器拖垮到时候就得手动用-j参数收敛。1.2 系统版本macOS 14 Sonoma 是实际起点Chromium 官方对 macOS 版本的最低要求其实比很多人印象里要高。原因在于编译工具链的依赖链条非常长macOS 系统版本决定你能装哪个版本的 XcodeXcode 决定 SDK 版本和内置 clang 版本而 Chromium 的构建脚本会对这些版本做严格校验。以 144 这个里程碑的经验来看macOS 13 Ventura 属于还能跑但开始吃紧的级别macOS 14 Sonoma 和 macOS 15 Sequoia 是更稳妥的选择。如果你的机器系统版本低于 macOS 13我建议先把系统升上来再折腾否则后续 gn 检查 Xcode 版本时大概率会直接报错。这里的核心逻辑是Chromium 太新它对工具链的底线要求会随着版本号不断抬升旧系统的 SDK 无法满足一些新特性和 ABI 要求。升级系统这件事本身也有讲究。不要用 OTA 覆盖式升级后直接开干有条件的话建议备份后做一次相对干净的升级因为 Chromium 工具链对系统的整洁度异常敏感系统里残留的旧开发工具、多个 Xcode 并存、手动改过系统目录权限都可能在编译阶段以难以理解的方式爆出来。1.3 Intel Mac 和 Apple Silicon架构不同准备策略也不同uname -m命令的输出决定了很多东西。Apple Silicon 上输出arm64Intel 上输出x86_64。Chromium 的构建系统会读取宿主机架构来设定默认的target_cpu也就是说 Apple Silicon 默认编 arm64 版本Intel 默认编 x64 版本。如果你在 Apple Silicon 上想交叉编译 x64 版本可以在 gn 参数里显式设置target_cpux64但这会失去原生架构的性能优势链接和运行都会通过 Rosetta 兜底慢不少。反过来Intel 机器上编 arm64 基本不现实构建速度和交叉编译的复杂度都划不来。所以我建议什么芯片就编什么架构不要一上来就折腾交叉编译。还有一个容易被忽略的点M 系列 Mac 上如果把 macOS 升级到 Sonoma 之后系统会默认把部分卷标为只读如果以前安装过乱七八糟的开发工具可能会在编译时触发代码签名或文件权限的问题。环境准备阶段不需要立刻处理这类问题但心里要有这根弦。2. 磁盘规划150GB 可用空间是保守值大小写敏感卷是隐藏要求磁盘规划是环境准备里最不性感、但翻车率最高的一环。Chromium 源码本身、构建缓存和中间产物三者的体量叠加起来对磁盘容量的消耗远超普通项目。我见过太多人在编译进行到一半时被 No space left on device 直接终结那种挫败感足以劝退大多数人。2.1 源码加构建产物到底吃掉多少空间先说源码侧。Chromium 采用单仓monorepo模式src目录下几乎包含了所有第三方依赖从 WebKit、V8 到各种音频视频编解码库全部在内。执行fetch chromium --no-history拉取当前快照后src目录体积大约在 20-30GB 之间。如果不用--no-history参数而把完整 git 历史也拉下来.git目录里的大历史对象会让整体体积翻几倍这也是我在后面章节强烈建议加--no-history的原因。构建产物的体量则取决于构建模式。下面是我在 macOS 上实测过的参考范围构建模式典型占用说明Debug symbol_level2100GB 以上调试符号极其占空间适合需要断点调试的场景Debug 组件构建 symbol_level040-60GB日常开发调试常用不开符号加快速度和省空间Release 组件构建 symbol_level025-40GB性能验证相关链接体积相对可控另外如果你打算启用 ccache 来加速二次编译缓存目录还得额外留出至少 30-50GB。官方文档确实写着 100GB 起步但那是最保守的数字我的建议是直接留出 150GB如果想开缓存或者做跨版本源码切换200GB 会更从容。2.2 创建大小写敏感的 APFS 卷这绝对是 macOS 编译 Chromium 环境准备里最容易被忽略、却最容易埋雷的一个点。macOS 默认的 APFS 文件系统是大小写不敏感case-insensitive的而 Chromium 官方明确要求源码必须放在大小写敏感case-sensitive的文件系统上。为什么会有这个要求因为 Chromium 和它依赖的大量第三方库在代码里存在仅靠大小写区分的文件或目录名比如Foo.h和foo.h同时存在于不同目录。在大小写不敏感的文件系统上这类文件在 checkout 或构建时可能出现文件互相覆盖、脚本找不到目标文件等灵异问题。这类报错通常不直观排查起来非常痛苦。解决办法是在现有 APFS 卷上新建一个大小写敏感的卷不需要重装系统也不需要重新分区。先查看当前磁盘信息diskutil list找到系统所在物理磁盘的标识符比如disk3然后执行sudo diskutil apfs addVolume disk3 APFSX ChromiumDev -mountpoint /Volumes/ChromiumDev这条命令会在disk3上创建一个名为ChromiumDev的新卷挂载到/Volumes/ChromiumDev。注意 APFSX 这个文件系统格式标记X 后缀就代表大小写敏感。创建完成后用df -h /Volumes/ChromiumDev确认卷已经挂载并且容量符合预期然后把所有 Chromium 相关源码都放到这个卷下面。提示不要把新卷的名字取得太复杂后面所有命令都要用到这个挂载路径越简单越不容易出错。有人可能想问我硬要在默认卷上编译行不行多数情况下确实能编出来但这是官方不支持的部署方式而且只要第三方依赖更新时出现一个大小写冲突的文件构建就会以一种极其反直觉的方式挂掉。既然要折腾 Chromium就别在文件系统这个地基上省事。2.3 固态硬盘和剩余空间的缓冲逻辑Chromium 源码里有几十万个文件checkout 和构建过程中会有海量的小文件读写操作。机械硬盘在这个场景下完全没有一战之力固态硬盘是硬性要求。Apple Silicon 机型全部标配 SSD这块问题不大但老款 Intel Mac 如果有外置机械硬盘作为源码盘建议趁早放弃。除了总容量剩余空间的缓冲也很关键。构建过程中会生成大量临时文件链接阶段的产物也会短时间内快速膨胀。如果磁盘剩余空间长期低于 20-30GBSSD 的垃圾回收和写入放大效应会拖慢编译速度极端情况下还会导致 clang 进程崩溃或链接器无法创建输出文件。我的经验是源码卷的可用空间从 150GB 开始每次构建结束后注意观察剩余容量变化如果发现空间一直往红线走就需要清理旧构建产物了。src下最占空间的通常是out目录删除不必要的构建输出可以直接释放大量空间rm -rf out/旧的构建目录名3. Xcode 与 Command Line Tools环境准备里最容易被低估的环节很多第一次接触 Chromium 编译的人对 Xcode 的理解是装个 IDE 而已但在这个项目里Xcode 的核心作用是提供编译 macOS 原生代码所需的 SDK、工具链以及系统库头文件。Chromium 编译对 Xcode 版本的敏感程度可以说远超一般项目。3.1 Xcode 正式版优先别用 beta 当主力Chromium 官方 CI 对工具链的跟进速度很快但默认情况下都是基于最新的稳定版 Xcode 做验证。beta 版 Xcode 不是不能用而是经常出现 chromium 构建脚本还没来得及适配的情况表现就是 gn 阶段直接报 SDK 版本不满足要求或者构建到一半链接器炸掉。我见过有人在 macOS 上装了 Xcode 26 beta折腾一整天才发现是版本适配问题。所以环境准备的原则就一条去 App Store 安装当前最新的正式版 Xcode。以 macOS 14/15 搭配 Chromium 144 的经验看Xcode 16.x 系列是合理的选择。安装过程需要下载好几个 GB 的安装包时间会比较长建议预留出充足时间不要边下载边编译。3.2 首次启动的许可协议与 xcode-select -pXcode 安装完成后很多人直接跑编译结果 gn 报错说找不到 Xcode 或者许可协议未接受。这是因为 Xcode 的许可证需要显式同意命令行工具才能正常工作。首次打开 Xcode 应用后它会弹窗要求同意协议如果没有图形界面操作条件也可以直接执行sudo xcodebuild -license accept接下来是比较关键的一步安装 Command Line Tools。这个组件经常被忽略因为 Xcode 本身带了一部分命令行工具但 Chromium 构建需要独立的 Command Line Tools 来配合工作xcode-select --install安装完成后务必验证当前激活的开发目录路径xcode-select -p正常情况下输出应该指向/Applications/Xcode.app/Contents/Developer如果输出的是/Library/Developer/CommandLineTools说明当前激活的是精简版命令行工具而不是完整 Xcodegn 会因为找不到完整 SDK 而报错。解决办法是用sudo xcode-select -s手动切换sudo xcode-select -s /Applications/Xcode.app/Contents/Developer这一步是环境准备中最容易翻车的细节很多人明明装了 Xcodegn 却报一堆 SDK 路径相关的错误根因就是xcode-select指向错了地方。3.3 验证编译器与 SDK 版本的匹配关系Xcode 安装并激活完成后还需要验证编译器工具链的状态。执行以下三组命令xcrun --show-sdk-path xcrun --show-sdk-version clang --version第一组命令输出 SDK 的完整路径第二组输出 SDK 版本号第三组输出编译器信息。正常状态下xcrun --show-sdk-path应该指向 Xcode 内部的MacOSX.sdk目录而不是 Command Line Tools 的 SDK 目录。如果这三项任意一项为空或报错说明 Xcode 安装不完整或路径有残留问题。关于版本匹配关系可以做一个粗略的参考操作系统版本建议 Xcode 版本说明macOS 15 SequoiaXcode 16.x搭配 Chromium 144 比较顺macOS 14 SonomaXcode 15.x 或 16.x需要确保 SDK 版本不被 Chromium 判定过旧macOS 13 VenturaXcode 15.x能用但可能出现版本告警Chromium 构建脚本对 Xcode 版本的容忍窗口比较窄版本太高或太低都可能被判定不可用。所以在正式动手之前先确认自己的 Xcode 版本在当前系统上能正常工作并且介于 Chromium 144 可接受的范围内。如果后续 gn 报出Xcode version does not meet minimum requirements这样的错误优先考虑升级 Xcode 而不是绕过检查。4. depot_toolsChromium 所有命令行工具的真正来源如果你之前编译过一些开源项目大概率习惯用 Homebrew 安装各种依赖工具。但在 Chromium 的世界里这个习惯要改一改。Chromium 官方维护了一套独立的命令行工具集叫 depot_toolsfetch、gclient、gn、ninja、autoninja 这些命令全部来自这里。4.1 克隆 depot_tools 的正确方式和目录位置不要用 Homebrew 安装 depot_tools。Homebrew 里的版本更新可能滞后于 Chromium 主线并且安装路径和官方预期不一致容易引发后续各种奇怪问题。官方推荐的方式是直接从 googlesource 克隆源码git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ~/depot_tools建议把 depot_tools 克隆到用户目录下的~/depot_tools这个路径在后续配置 PATH 时最自然。克隆完成后目录里已经有了一系列可执行脚本但还需要把目录加入 PATH 才能让系统找到这些命令。4.2 PATH 配置与自动更新机制打开~/.zshrc如果用的是 zsh或~/.bashrc如果用的是 bash在文件头部加入export PATH$HOME/depot_tools:$PATH然后重新加载配置source ~/.zshrc或者直接新开一个终端窗口。这里有一个细节值得注意$HOME/depot_tools一定要放在 PATH 的最前面不要追加在末尾。原因是某些 macOS 系统自带或 Homebrew 安装的工具可能与 depot_tools 中的同名命令冲突把 depot_tools 放在前面可以确保系统优先执行 Chromium 官方版本。depot_tools 还有一套自动更新机制。每次执行gclient、fetch等命令时它会先检查自身是否有更新有就自动拉取。这套机制在个人开发环境里建议保留它保证了工具链和 Chromium 主线的同步。如果在 CI 环境里可以用环境变量DEPOT_TOOLS_UPDATE0禁掉自动更新避免每次构建都被拉取动作拖慢。4.3 为什么 fetch、gn、ninja、gclient 都从这里来很多人第一次接触 Chromium 构建时会被这一堆工具搞糊涂。简单梳理一下各自的职责fetch负责初始化项目、拉取主源码和第三方依赖。gclientChromium 的依赖管理工具相当于其他项目里的git submodule和包管理器的结合体。gn元构建系统负责根据构建参数生成 Ninja 构建文件。它不直接编译代码而是产生如何编译的蓝图。ninja真正的构建执行器负责调度编译和链接任务。它的核心优势是增量构建和并行调度能力。autoninja对 ninja 的封装会自动根据机器核心数和内存情况设置合理的并发参数。把这套工具想成一条流水线fetch把原料拉回来gclient整理依赖关系gn画好施工图ninja负责按图施工。后续所有操作都离不开这条流水线而它们全都位于~/depot_tools目录下。配置完成后可以做一次快速验证gclient --version fetch --help gn --versionfetch --help能正常输出说明命令已经生效。gn --version首次运行时会尝试下载预编译的 gn 二进制需要网络畅通看到版本号输出就说明 depot_tools 这一环已经通了。5. fetch chromium --no-history第一次拉取源码的完整动作环境准备到这里距离真正动手只剩一步把源码拉下来。这一步的动作很简单但有非常多的细节值得讲究。5.1 源码根目录的组织方式和 .gclient 配置在大小写敏感的磁盘卷下新建一个目录比如前面创建的/Volumes/ChromiumDev/chromiummkdir -p /Volumes/ChromiumDev/chromium cd /Volumes/ChromiumDev/chromium然后在当前目录下执行 fetchfetch chromium --no-history这里的--no-history参数非常关键。Chromium 的 git 历史非常庞大完整拉取的话光历史记录就能占用几十上百 GB下载时间和磁盘消耗都会成倍增加。对于大多数只想编译和开发的人来说历史记录没有太大价值--no-history只拉取当前代码快照干净利落。fetch 过程会自动创建.gclient文件。这个文件记录了项目的依赖配置初始内容大致长这样solutions [ { name: src, url: https://chromium.googlesource.com/chromium/src.git, managed: False, custom_deps: {}, custom_vars: {}, }, ].gclient文件告诉 gclient 工具主源码的位置以及需要同步哪些依赖。如果后续想配置 iOS 交叉编译或其他目标平台就在这个文件里加target_os字段但 macOS 原生构建一般不需要改动。5.2 拉取耗时、过程观察与断点续传fetch 的耗时取决于网络状况和磁盘速度常见的区间在半小时到两小时。期间终端会滚动大量输出主要分两个阶段第一阶段是 git 拉取主仓库第二阶段是 gclient 同步第三方依赖。后者会列出一个个子项目名和进度比如third_party/llvm、v8、webrtc这些重头戏每一个都可能单独下载几百 MB 到几个 GB。整个过程比较枯燥但不建议全程盯着终端。有一个经验可以分享fetch 过程中如果因为网络波动或休眠导致中断不要慌直接重新执行一遍fetch chromium --no-historygit 和 gclient 都支持断点续传已经下载完的部分不会重新来一遍。千万不要因为中断就删掉目录重下那样反而浪费更多时间。判断 fetch 是否完成的标志是gclient 的同步阶段结束进入Running hooks阶段并且最终没有 fatal error 输出。Hooks 是 Chromium 构建系统在源码同步完成后自动执行的一些脚本任务比如下载构建工具链、生成必要的补丁文件等。看到 hooks 跑完说明这次拉取基本成功了。5.3 拉完后先别急着编译检查这几个关键文件fetch 完成后不要急着立刻跳到 gn 阶段先花两分钟做几个确认cd src cat chrome/VERSION ls -d buildtools/ third_party/llvm/cat chrome/VERSION会输出类似这样的内容MAJOR144 MINOR0 BUILDXXXX PATCHXXXX确认MAJOR144就说明当前代码确实就是目标里程碑。检查buildtools和third_party/llvm是否存在这两个目录是构建的关键依赖如果缺失后续 gn 和 ninja 都会报错。如果 fetch 过程中终端输出显示一切正常但目录结构感觉不对可以再补跑一次同步gclient syncgclient sync会重新检查所有依赖是否完整并自动补下载缺失部分。如果需要重新执行源码生成阶段的脚本也可以跑gclient runhooks这一步会重新执行依赖中的 hook 脚本通常在升级 Xcode 或切换系统 SDK 版本后特别有用。6. 最小验证gn gen 跑通环境准备才算真正结束源码拉完环境准备看起来完成了但我个人衡量环境是否就绪的标准从来不是装了 Xcode或者拉完了代码而是gn gen能顺利跑出一个构建目录。这个验证过不了后面全是空中楼阁。6.1 首次 gn gen 的参数怎么给进入src目录第一次生成构建文件的时候参数建议简洁克制。我的建议是先做一次 Release 风格的组件构建验证参数如下cd /Volumes/ChromiumDev/chromium/src gn gen out/Default --argsis_debugfalse is_component_buildtrue symbol_level0逐个解释这几个参数is_debugfalse生成 Release 配置不额外注入调试符号信息编译速度更快产出体积更小。is_component_buildtrue组件构建模式把整个 Chromium 拆分成一系列动态库而不是链接成一个巨型可执行文件。这个模式能大幅降低链接阶段的内存压力和时长是日常开发验证的首选。symbol_level0不生成调试符号。环境验证阶段不需要符号等后面真正需要断点调试再单独开。如果你后面打算完整调试 Chromium 源码可以换成is_debugtrue加默认的symbol_level2但磁盘和内存压力会成倍上升不建议在环境准备阶段就开满。gn gen成功时输出会显示生成的 build.ninja 文件路径以及类似 Done. Made xxx targets 的信息。同时out/Default目录下会生成args.gn和build.ninja两个关键文件。看到这个输出说明环境配置已经通了。6.2 三个高频首跑报错与根因分析环境准备阶段最容易撞上的报错其实非常固定我整理成了一张对照表遇到问题可以直接对着排查报错现象根本原因解决方案gn: command not founddepot_tools 没有加入 PATH或 PATH 顺序不对检查source ~/.zshrc是否执行确认which gn指向~/depot_toolsXcode version does not meet minimum requirementsXcode 版本过旧或者路径指向了 Command Line Tools升级到正式版 Xcodesudo xcode-select -s切换到完整 XcodeNo space left on device磁盘容量或卷容量不足清理旧构建产物给源码卷留出至少 50GB 以上空间第一个报错最常见的原因是配置完 PATH 后没有重新加载配置或者新开的终端没有读取到~/.zshrc。第二个报错很多时候不是 Xcode 版本真的老而是xcode-select -p输出了错误路径。第三个报错则要从两方面看总磁盘空间不足是表层深层原因可能是大小写敏感卷创建时分配的容量不够需要先用diskutil apfs resize调整卷容量。还有一个不那么高频但同样容易误判的报错是FATAL: xcode-select: error: tool xcodebuild requires Xcode, but system active developer directory is /Library/Developer/CommandLineTools。这个英文报错已经把答案说得很直白了就是系统激活的开发目录不对同样的解法切回完整 Xcode 路径即可。6.3 验证完成后的个人建议gn gen通过之后环境准备这个阶段才算真正收口。但如果你想让这次准备更扎实我建议再做一步轻量级验证编译一个体积较小的基础库确认编译器工具链和 Ninja 调度真正能跑通。进入src目录执行autoninja -C out/Default basebase是 Chromium 的基础库依赖相对少编译时间通常控制在几分钟到十几分钟却能完整覆盖 clang 编译、链接、产物生成这一整条链路。看到base库的链接产物生成就说明从 Xcode 到 depot_tools 再到源码目录的每一环都已经打通了。这时候你可能会想干脆直接编全量chrome目标我的建议是不要急。全量chrome链接在普通配置的机器上可能要跑几十分钟到几个小时而且内存不足时很容易在链接阶段直接爆掉。先把base这样的小目标跑通确认环境稳定后续再逐步加大目标排查问题时会轻松很多。环境准备的验证到这里就完成了。对我个人来说判断 macOS 环境是否真的准备好从来不是装完了 Xcode或者拉完了代码而是gn gen之后能稳定跑完base这样一个基础目标的编译。这一步跑通后面的构建才有意义排查问题也才有参照系。下一篇我会展开讲gn args的完整参数选择和 Ninja 构建的实战调优。