1. 从零到一：为什么我们需要自己编译Chromium？

如果你是一名前端开发者、浏览器插件作者，或者像我一样，对浏览器底层技术充满好奇，那么“自己编译Chromium”这个念头可能不止一次在你脑海中闪过。网上随手一搜，就能找到各种“一键编译脚本”或“精简指南”，但真正动手后，你会发现从下载源码到看到那个熟悉的“关于Chromium”对话框弹出来，中间隔着无数个令人崩溃的编译错误、几十GB的磁盘占用和长达数小时甚至数天的等待。那么，我们为什么要自讨苦吃，去折腾这个庞然大物呢？

简单来说，自己编译Chromium，不是为了得到一个能上网的浏览器——官方或第三方构建的版本多得是。核心驱动力在于“控制”与“定制”。当你需要深度调试一个仅在特定版本或架构下出现的渲染Bug时；当你打算开发一个需要修改浏览器内核本身才能实现的高级扩展或嵌入式应用时；或者当你研究的领域涉及浏览器安全、新的Web标准实现时，一个完全由你掌控的、可调试的Chromium构建版本，就是不可替代的“实验室”。它能让你看到每一行代码的变动如何影响最终行为，这是使用预编译二进制文件永远无法获得的体验。此外，对于国内开发者而言，自己编译也能绕过一些网络环境带来的依赖下载难题，虽然过程依然曲折。

2. 战前准备：理解Chromium编译的“巨兽”本质与资源门槛

在敲下任何命令之前，我们必须清醒地认识到，编译Chromium是一项资源密集型工程，它对你的硬件、网络和耐心都是巨大的考验。这不是在编译一个hello world，而是在构建一个拥有数千万行代码、依赖关系极其复杂的现代操作系统级应用。

2.1 硬件与系统要求：没有足够的资源，一切免谈

官方文档会给出一个最低配置，但根据我的经验，那仅仅是“能跑”的标准。如果你想在合理的时间内（比如一个下午）完成构建，我强烈建议以下配置：

• 操作系统：Linux（如Ubuntu 20.04 LTS或更高版本）是首选，无论是WSL2下的Ubuntu还是实体机。macOS也可以，但某些工具链的配置可能更繁琐。Windows原生支持，但环境搭建最复杂，坑最多。
• CPU：至少8核，强烈推荐16核或更多。编译过程极度并行化，核心数直接决定编译速度。
• 内存：16GB是起步价，32GB或以上才能让你在编译时还能流畅地做点别的事情。链接阶段（特别是chrome目标）是内存吞噬怪兽，我曾亲眼见过它吃掉超过20GB的内存。
• 硬盘：准备至少100GB的可用空间。源码、构建输出、缓存等加起来，轻松突破80GB。使用SSD是必须的，机械硬盘的IO性能会使得编译时间呈指数级增长。
• 网络：稳定、高速的网络连接至关重要。初始的depot_tools和源码同步，以及后续通过gclient拉取依赖，都需要从Google的服务器下载海量数据。网络不稳定可能导致同步失败，需要重试。

注意：在虚拟机或资源受限的云主机上尝试编译，通常是一场灾难。编译过程可能因内存不足（OOM）而崩溃，或因CPU争抢导致系统无响应。

2.2 工具链部署：depot_tools——Chromium世界的“瑞士军刀”

Chromium项目使用一套名为depot_tools的自定义工具集来管理代码和构建。这是整个流程的基石。

1. 获取depot_tools：

   # 选择一个合适的目录，比如你的家目录 cd ~ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

2. 将其加入PATH环境变量： 这是最关键的一步，必须确保在后续所有操作中，depot_tools的路径在系统PATH的最前面。

   # 对于bash/zsh用户，将以下内容添加到 ~/.bashrc 或 ~/.zshrc 文件末尾 export PATH="$PATH:/path/to/depot_tools" # 请将 /path/to 替换为你的实际路径，例如 /home/yourname/depot_tools

   然后执行source ~/.bashrc使配置生效。你可以通过which gclient命令来验证，它应该指向depot_tools目录下的脚本。

3. 避免Root权限：整个Chromium的获取和编译过程都不应该使用root权限。在你的普通用户目录下操作即可。

3. 源码获取与同步：一场与时间和网络的赛跑

有了工具，接下来就是获取这座“代码山”。

3.1 创建目录与初始化

Chromium的源码树非常庞大，单独创建一个目录是个好习惯。

mkdir ~/chromium && cd ~/chromium

接下来，使用depot_tools中的fetch命令来获取代码。这里有一个至关重要的选择：是获取整个Chromium项目，还是只获取你需要的部分（比如仅用于开发的chromium/src）？

对于绝大多数开发者，我推荐使用--no-history参数来获取一个浅克隆，这能节省大量时间和磁盘空间，因为你不需要完整的git历史记录。

fetch --nohooks chromium

如果你需要Android或iOS的交叉编译支持，则需要对应的参数，如fetch android或fetch ios。但首次编译，建议从基础的chromium开始。

这个命令会启动一个漫长的过程：它首先会下载一个“引导”仓库，然后运行gclient sync来解析DEPS文件，拉取所有依赖的子项目（如V8、Skia、WebRTC等）。这个过程完全依赖于网络，且必须能够访问Google的相关服务。如果遇到网络问题，你可能需要配置HTTP/HTTPS代理。

3.2 处理同步过程中的依赖与钩子

fetch命令中的--nohooks意味着它不会在同步后立即运行“钩子”（hooks）。钩子是一些自动化的脚本，用于下载特定平台的构建依赖（如系统库、SDK）和生成必要的构建文件。

在源码同步完成后，你需要手动运行钩子：

cd ~/chromium/src gclient runhooks

这个步骤会下载诸如clang编译器、nacl工具链、特定版本的Python等构建必需品。同样，它也需要网络。在Linux上，它可能会通过apt-get或类似命令安装一些系统包，请确保你有相应的权限。

3.3 版本选择与代码切换

默认情况下，fetch会拉取主线（main）的最新代码，但这可能是不稳定的。为了获得一个已知稳定的构建环境，你可以切换到某个特定的标签或分支。

# 首先查看可用的分支/标签 git fetch --tags git branch -r | grep -E \"branch-heads/[0-9]+\" | tail -10 # 切换到某个稳定的分支，例如 120.0.6099.5 对应的分支 git checkout -b my_build branch-heads/6099

切换分支后，必须再次运行gclient sync来更新依赖到与该分支匹配的状态：

gclient sync --with_branch_heads --with_tags

忽略这一步是导致后续编译失败的最常见原因之一，因为不同版本的Chromium源码可能依赖不同版本的子项目。

4. 构建配置生成：用GN定义你的“定制浏览器”

Chromium抛弃了传统的GNU Autotools或CMake，使用了Google自家开发的GN（Generate Ninja）作为元构建系统。它的输入是.gn和.gni文件，输出是Ninja构建文件。我们需要在构建前进行配置。

4.1 创建输出目录并运行gn args

在src目录下，为你的构建创建一个输出目录（例如out/Default），并进入配置界面：

cd ~/chromium/src gn args out/Default

这条命令会打开一个文本编辑器（默认为nano或vi），让你编辑构建参数。这些参数将决定编译出的Chromium具有哪些特性。

4.2 关键构建参数解析

以下是一份针对开发者调试的常用配置示例，你可以在编辑器中输入：

# 设置构建类型为“调试”，包含符号信息，便于调试但体积巨大、速度慢 is_debug = true # 关闭官方构建模式，否则会强制使用一些Google内部的优化和设置 is_official_build = false # 启用组件构建（component build）。这是调试的神器！ # 它将Chromium拆分成数百个小的共享库（.so），而非单个巨大可执行文件。 # 好处：增量编译极快，链接时间几乎为零。 # 坏处：程序启动慢（因为要加载大量动态库），最终分发不便。 is_component_build = true # 关闭符号剥离，保留所有调试符号 symbol_level = 2 # 启用运行时栈检查和安全检查，帮助发现内存错误 enable_nacl = false # 通常不需要NaCl blink_symbol_level = 2 # 为Blink引擎也保留完整符号 # 目标CPU架构（根据你的机器选择） target_cpu = \"x64\" # 对于AMD64/Intel 64位 # target_cpu = \"arm64\" # 对于Apple Silicon Mac或ARM Linux # 关闭一些非必要的子系统以加速编译（可选） enable_google_now = false enable_remoting = false

保存并退出编辑器后，GN会根据这些参数生成out/Default/args.gn文件和对应的Ninja构建文件。

实操心得：对于第一次编译，强烈建议使用is_component_build=true。它能将漫长的全量链接时间分摊到每次小的增量编译中，极大提升开发迭代效率。当你需要生成一个用于性能测试或分发的版本时，再改用is_component_build=false和is_debug=false进行“发布（Release）”构建。

5. 启动编译与问题排查：耐心等待与见招拆招

配置完毕，激动人心的编译时刻到了。使用Ninja进行构建：

# 使用 autoninja 工具（来自depot_tools），它能自动设置最优的并行任务数（-j参数） autoninja -C out/Default chrome

这里的chrome是构建目标，它代表了完整的Chromium浏览器。你也可以编译其他目标，如unit_tests（单元测试）、browser_tests（浏览器测试）或chromedriver。

接下来，就是一场漫长的等待。在16核CPU、32GB内存、NVMe SSD的机器上，首次完整构建Debug版本的chrome可能需要2到6个小时。期间，你的机器会风扇狂转，CPU占用率持续100%。

5.1 编译过程中常见的“坑”与解决方案

1. 内存不足（OOM Killer）：现象：编译进程突然消失，系统日志（dmesg或/var/log/kern.log）中出现Out of memory: Kill process记录。解决：

   • 增加物理内存或交换空间（swap）。可以临时创建一个大的swap文件：

     sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

   • 减少并行编译任务数。虽然autoninja很智能，但你也可以手动指定更少的-j值：

     ninja -C out/Default -j 4 chrome # 只使用4个任务

   • 如果是component build，链接阶段内存压力小，此问题较少见。

2. 磁盘空间不足：现象：编译失败，报错No space left on device。解决：清理系统无用文件，或为编译目录挂载一个更大容量的磁盘。编译中间文件（在out/Default下）非常庞大。

3. 网络依赖下载失败：现象：在gclient sync或gclient runhooks阶段，卡在某个资源下载，或报SSL/HTTP错误。解决：

   • 配置git和curl的代理（如果网络环境需要）。
   • 尝试多次重试命令。有时是暂时的网络波动。
   • 检查depot_tools是否在PATH最前面，且版本最新（gclient自更新）。

4. 奇怪的编译错误（如‘undefined reference’）：现象：编译到某个阶段，报链接错误或找不到符号。解决：

   • 首先确保代码完全同步：cd src && git status确保工作区干净，然后gclient sync。
   • 清理构建目录：有时旧的构建产物会干扰。可以尝试gn clean out/Default，然后重新gn args和autoninja。注意，这会清空所有中间文件，需要从头编译。
   • 检查GN参数：确认参数没有冲突。例如，某些参数可能不适用于component build。

5.2 编译成功与首次运行

当终端最后出现类似[100%] All targets were successfully built.的提示时，恭喜你！

编译产物位于out/Default目录下。最重要的可执行文件是：

• Linux:./chrome或./chrome-wrapper
• macOS:Chromium.app/Contents/MacOS/Chromium
• Windows:chrome.exe

直接运行它：

cd ~/chromium/src out/Default/chrome

你第一次运行自己编译的Chromium时，可能会感觉启动速度比官方版慢（尤其是Debug+Component构建），这是正常的。你应该能看到浏览器窗口，并且在“关于Chromium”中，版本号会包含你本地的提交哈希，而不是官方版本号。

6. 进阶：从“能编译”到“会使用”

成功编译出浏览器只是一个开始。要让这个自编译的Chromium真正为你的开发或研究服务，还需要掌握一些进阶技巧。

6.1 高效的开发工作流：增量编译与测试

这是自编译Chromium最大的优势所在。假设你修改了src/components/button里的一个C++文件：

1. 增量编译：只需重新运行autoninja -C out/Default chrome，Ninja会智能地只编译受影响的目标和链接最终产物。在component build模式下，这个过程通常只需要几秒到几十秒。
2. 运行测试：Chromium有庞大的测试套件。你可以编译并运行特定测试：

   # 编译所有测试（耗时） autoninja -C out/Default unit_tests browser_tests # 运行某个具体的测试用例 out/Default/unit_tests --gtest_filter=\"ButtonTest.*\"

3. 调试：使用GDB（Linux）、LLDB（macOS）或Visual Studio（Windows）直接附加到chrome进程，或者从IDE启动。由于是Debug构建并带有完整符号，你可以轻松设置断点、查看变量、单步执行，深入到Blink渲染引擎或V8 JavaScript引擎的内部。

6.2 定制化修改与打补丁

你编译Chromium的目的很可能就是为了修改它。流程如下：

1. 在本地分支上工作：永远不要在main分支上直接修改。git checkout -b my_feature。
2. 进行代码修改。
3. 编译测试：如上所述进行增量编译和测试。
4. 提交：git commit -am \"Implement my awesome feature\"。
5. 生成补丁（如需提交给上游）：git format-patch main --stdout > my_feature.patch。

6.3 构建类型的取舍：Debug, Release, Official

• Debug (is_debug=true)：包含断言、调试符号、未优化。运行慢，体积大，适合开发和调试。
• Release (is_debug=false)：开启编译器优化（如-O2），剥离调试符号。运行快，体积小，适合性能测试和日常使用。
• Official Build (is_official_build=true)：在Release基础上，使用特定的编译器标志、版本信息，并可能启用一些专有代码路径。这通常是Google发布Chrome时使用的配置。个人编译通常不需要。

你可以创建多个输出目录来管理不同配置：

gn args out/Debug # 配置为调试版 gn args out/Release # 配置为发布版 autoninja -C out/Debug chrome autoninja -C out/Release chrome

7. 疑难杂症与资源索引

即使遵循了所有步骤，你仍可能遇到独特的问题。这里有一些排查思路和资源：

• 查看完整错误日志：Ninja的错误输出有时只是最后一步。查看编译开始附近的错误，或者尝试减少并行任务数（-j 1）来获得更清晰的错误流。
• 搜索错误信息：将错误信息的关键部分复制，在Chromium的官方论坛（groups.google.com/a/chromium.org）、Bug追踪系统（bugs.chromium.org）或Stack Overflow上搜索。你遇到的问题，很可能别人已经遇到并解决了。
• 检查系统依赖：确保所有必要的系统库都已安装。在Ubuntu上，你可以尝试运行src/build/install-build-deps.sh脚本来安装大多数依赖（注意它会安装很多包）。
• 核验工具版本：确保你的depot_tools、Python、clang（由gclient runhooks下载）版本符合要求。过旧或过新的系统编译器（如GCC）可能导致问题。
• 从头再来的勇气：如果代码树或构建目录处于一个无法修复的混乱状态，最彻底的办法就是：删除整个src目录和out目录，按照本文步骤从头开始。这很耗时，但往往能解决一些玄学问题。

自己编译Chromium是一次充满挑战但收获巨大的旅程。它不仅仅让你获得了一个浏览器，更让你深入理解了现代大型C++项目的构建体系、依赖管理和开发流程。当你第一次用自己的二进制文件打开网页，并在自己修改的代码处命中断点时，那种成就感是无与伦比的。这个过程会逼着你熟悉Linux系统管理、网络调试、性能分析等一系列技能。所以，准备好你的机器，调整好心态，开始这场与代码巨人的对话吧。记住，每一个编译错误都是一个学习的机会。