1. 项目概述为什么我们要亲手编译Chromium如果你是一名前端开发者、浏览器内核研究者或者像我一样对浏览器这个现代互联网的基石抱有强烈的好奇心那么“编译Chromium”这个念头可能不止一次在你脑海中闪过。这绝不仅仅是为了得到一个“自己编译的浏览器”那么简单。市面上现成的Chrome、Edge已经足够好用我们之所以愿意投入数十小时甚至数天的时间去折腾这个庞大的、超过30GB的代码库背后有更深层的驱动力。最直接的需求是定制化。你是否曾想过移除浏览器里你不想要的功能比如某些数据上报模块或者你想为浏览器添加一个实验性的新特性比如修改网络协议栈的行为再或者你正在开发一个基于Chromium的桌面应用比如Electron的某个深度定制版本需要针对特定硬件或操作系统进行极致优化这些都绕不开从源码构建这一步。只有掌握了编译你才真正拥有了“改造”这个庞然大物的能力。其次是深度调试与问题排查。当你在开发一个复杂的Web应用或浏览器插件时遇到一个只在特定版本或特定场景下出现的诡异Bug如何定位如果这个Bug可能存在于浏览器内核中查看和调试Chromium源码就成了唯一途径。而调试符号最完整、最能反映真实运行状态的正是你自己编译出来的版本。你可以随意打日志、下断点像外科手术一样剖析浏览器的内部运作。最后对于学习者而言这是一个无与伦比的学习项目。Chromium几乎涵盖了现代大型C项目的所有最佳实践复杂的多进程架构、跨平台构建系统GN/Ninja、沙箱安全机制、Blink渲染引擎、V8 JavaScript引擎等等。通过配置环境、解决依赖、追踪编译错误你能学到远比“如何使用浏览器”多得多的知识。这就像不是去参观一辆跑车而是亲手在工厂里从图纸开始把它组装起来。当然这个过程绝不轻松。它对你的机器性能尤其是磁盘空间、内存和CPU、网络环境以及排错能力都是一次严峻的考验。但一旦成功你获得的不仅仅是一个可执行文件更是一张通往浏览器技术深水区的“通行证”。接下来我将把我多次编译Chromium的经验从环境准备到问题排查毫无保留地分享给你。2. 编译前的核心准备硬件、系统与工具链在开始下载那海量的代码之前我们必须把地基打牢。错误的起步会导致后续步骤连环报错浪费大量时间。这里的每一个选择都直接关系到编译的成功率和耗时。2.1 硬件与系统要求这不是普通项目Chromium的官方文档会给出一个最低配置但相信我按最低配置来你的编译过程会痛苦不堪。以下是我基于实际体验的“舒适”配置建议操作系统Linux首选Ubuntu LTS版本如20.04或22.04或macOS。Windows也可以但涉及Visual Studio和复杂的路径问题环境配置的复杂度会高一个数量级。本文将以Ubuntu 22.04 LTS为主要环境进行说明这是社区支持最完善、问题最少的路径。CPU至少8核强烈推荐16核或更多。编译是高度并行化的任务核心数直接决定编译速度。我的经验是从8核升级到16核编译时间几乎减半。内存32GB是起步价64GB会让你在链接Linking阶段更加从容。当Ninja启动所有编译进程时内存占用会飙升。16GB内存的机器在完整编译时极有可能因内存不足OOM而被系统杀死进程。磁盘空间准备至少150GB的可用空间。这包括代码仓库约30GB、构建输出目录Debug版可能超过80GB、以及各种缓存和中间文件。使用SSD是必须的机械硬盘的IO速度会使得编译过程漫长到令人绝望。网络稳定、高速的网络连接。首次同步代码需要下载数十GB的数据任何中断都可能需要重来。注意很多人低估了磁盘空间需求。一个完整的Debug构建目录out/Default轻松超过80GB。如果你打算同时保留Debug和Release构建或者尝试不同的构建参数请务必预留200GB以上的空间。我曾亲眼见过同事因为磁盘空间不足在编译最后阶段失败前功尽弃。2.2 工具链安装与配置步步为营在Ubuntu上我们需要安装一系列基础工具和Chromium特有的依赖。更新系统并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y git curl wget python3 python3-pip安装Chromium构建依赖 这是最关键的一步。Chromium团队提供了一个非常方便的脚本可以自动安装所有必需的库和工具。# 首先获取该脚本 curl -O https://chromium.googlesource.com/chromium/src//main/build/install-build-deps.sh?formatTEXT # 注意上面的链接需要处理。更可靠的方式是先克隆代码仓库后续步骤然后使用仓库里的脚本。 # 但我们可以先手动安装主要依赖一个更精简的集合 sudo apt install -y \ git \ curl \ wget \ python3 \ python3-pip \ ninja-build \ pkg-config \ lsb-release \ libglib2.0-dev \ libnss3-dev \ libatk1.0-dev \ libatk-bridge2.0-dev \ libxdamage-dev \ libxkbcommon-dev \ libxcomposite-dev \ libxrandr-dev \ libgbm-dev \ libasound2-dev \ libpango1.0-dev实际上最省心的办法是后续通过depot_tools中的gclient来运行安装依赖的脚本。安装并配置depot_toolsdepot_tools是Google为Chromium、V8等项目开发的一套仓库管理工具集包含了gclient、fetch、gn、ninja等核心工具。它必须被正确配置到环境变量中。# 1. 克隆 depot_tools 仓库 git clone https://chromium.googleslesource.com/chromium/tools/depot_tools.git ~/depot_tools # 2. 将其添加到PATH环境变量的最前面至关重要 echo export PATH$HOME/depot_tools:$PATH ~/.bashrc source ~/.bashrc # 3. 验证安装 which gclient which fetch实操心得PATH的顺序非常重要。必须确保~/depot_tools在系统其他路径之前。因为depot_tools自带了一个特定版本的python、git和ninja编译过程依赖于这些特定版本。如果系统自带的版本在前可能会导致难以预料的错误。3. 获取源码与构建配置与数十GB代码的第一次接触环境就绪后我们开始获取这个世界上最大、最活跃的单体代码仓库之一。3.1 获取Chromium源码我们不直接使用git clone而是使用depot_tools提供的fetch脚本它能处理Chromium复杂的多仓库依赖关系。# 创建一个专门的工作目录并进入 mkdir ~/chromium cd ~/chromium # 使用 fetch 工具获取代码。这里我们获取主线代码main branch。 # 注意这个过程会非常漫长取决于你的网速可能需要数小时。 fetch --nohooks chromium--nohooks参数表示先不运行钩子脚本hooks我们先拉取代码主体。钩子脚本会下载一些额外的二进制依赖如特定版本的Clang编译器、SDK等我们可以在代码拉取完成后单独运行。如果网络中断可以重新进入目录运行gclient sync继续同步。3.2 运行钩子脚本与安装额外依赖代码拉取完成后需要运行钩子脚本下载编译所需的工具链。cd src gclient runhooks这个过程同样会下载数GB的数据。完成后工具链如Clang编译器就准备就绪了。3.3 生成构建配置GN与Ninja的协作Chromium使用GN (Generate Ninja)作为元构建系统它根据我们的配置生成build.ninja文件然后由Ninja这个极速构建工具执行实际的编译任务。首先我们需要创建一个构建目录并生成配置。最常用的构建目录是out/Default用于开发调试和out/Release用于发布。# 确保在 src/ 目录下 # 使用 gn 工具生成 args.gn 配置文件 gn args out/Default执行这条命令会打开一个文本编辑器如nano或vim。在这里我们需要输入构建参数。以下是一个适合首次编译、用于调试的配置示例# 设置构建目标操作系统和CPU架构 target_os linux target_cpu x64 # 启用官方构建模式会启用一些优化但比纯Debug快 is_debug false is_official_build true # 关闭符号剥离便于调试 symbol_level 1 strip_debug_info false # 启用组件构建重要 is_component_build true # 设置编译并行数通常等于CPU核心数 # 但如果你内存紧张可以适当调低比如 j4 jumbo_file_merge_limit 8保存并退出编辑器后GN会根据这些参数生成对应的build.ninja文件。核心参数解析is_component_build true这是新手最重要的设置。它开启“组件化构建”将Chromium拆分成数百个小的共享库.so文件而不是链接成一个巨大的单一可执行文件。这极大地减少了每次增量编译时的链接时间对开发调试至关重要。缺点是首次编译时间稍长且最终产物包含大量小文件。symbol_level 1保留足够的调试符号让你可以在GDB或LLDB中看到函数名和基本结构但又不会像symbol_level 2完全调试符号那样让二进制文件体积爆炸。is_official_build true与is_debug false结合这是一种折中方案。它比纯Debug构建is_debug true更快、产物更小同时开启了许多优化适合日常开发和功能测试。纯Debug构建主要用于深入的单步调试。4. 启动编译与监控一场对耐心的考验配置完成后激动人心的编译时刻就到了。# 在 src/ 目录下使用 autoninja 启动编译。 # autoninja 是 depot_tools 提供的包装脚本能自动设置合适的并行任务数-j。 autoninja -C out/Default chrome这里的-C out/Default指定构建目录chrome是我们要构建的目标生成名为chrome的可执行文件。你也可以构建其他目标如unit_tests单元测试。按下回车后你的终端将开始疯狂刷屏。风扇开始呼啸这是你的CPU和内存正在接受洗礼。首次完整编译在配置良好的机器上如16核/64GB/SSD可能需要2到6个小时。如何监控编译过程看输出Ninja会显示当前正在编译的文件、已完成的百分比以及预估剩余时间。关注是否有红色的错误信息。系统监控打开htop或gnome-system-monitor观察CPU是否满载内存使用是否健康。磁盘空间定期用df -h检查磁盘剩余空间尤其是out/Default所在的分区。注意事项编译过程中最可能遇到的两种失败内存不足OOM系统开始使用Swap然后编译进程被杀死。解决方案只能是增加物理内存或者减少并行编译任务数在gn args中设置jumbo_file_merge_limit为一个更小的值或者使用ninja -j 4 chrome手动指定低并行度。磁盘空间不足编译戛然而止。请务必在开始前清理出足够空间。如果中途空间不足可以尝试删除out/Default目录重新开始虽然痛苦或者尝试只构建更小的目标。编译成功完成后你会在out/Default目录下找到chrome可执行文件。运行它./out/Default/chrome恭喜你现在运行的是由你亲手编译的、独一无二的Chromium浏览器。它可能还没有品牌Logo是一个蓝色的地球图标但功能与官方版基本一致。5. 增量编译与日常开发工作流首次编译成功后后续的开发工作就轻松多了。你不需要每次都从头开始。5.1 代码更新与同步当你想同步最新的上游代码时# 在 src/ 目录下 git rebase-update # 这是一个 depot_tools 脚本用于拉取并变基代码 gclient syncgclient sync会同步所有子仓库的代码并自动运行钩子脚本更新工具链。5.2 进行增量编译假设你只修改了一两个文件想重新编译并测试# 仍然在 src/ 目录下 autoninja -C out/Default chromeNinja非常智能它会精确地只编译那些受你修改影响的源文件然后重新链接必要的组件。这个过程通常只需要几十秒到几分钟这才是高效的开发体验。5.3 运行特定测试Chromium有海量的自动化测试。你可以编译和运行特定的测试套件# 编译所有单元测试 autoninja -C out/Default unit_tests # 运行某个具体的测试比如 base 库的测试 ./out/Default/unit_tests --gtest_filterBaseTest.* # 编译并运行浏览器测试会更慢 autoninja -C out/Default browser_tests ./out/Default/browser_tests --gtest_filterBrowserTest.*6. 高级配置与自定义构建当你熟悉基础编译后可能会需要一些更高级的配置。6.1 构建Release版本Release版本去除了调试信息开启了所有优化体积更小速度更快适合性能测试或分发。gn args out/Release在编辑器中输入target_os linux target_cpu x64 is_debug false is_official_build true is_component_build false # Release版通常关闭组件构建生成单一二进制 symbol_level 0 # 不包含调试符号然后编译autoninja -C out/Release chrome6.2 启用或禁用特定功能GN系统允许你精细控制编译开关。例如你想禁用对PDF的原生支持使用系统插件或外部查看器# 在 args.gn 中添加 pdf_enable_v8 false pdf_enable_xfa false enable_pdf_viewer false你可以通过gn args out/Default --list查看所有可用的参数并用grep过滤例如gn args out/Default --list | grep blink查看所有与Blink引擎相关的参数。6.3 交叉编译例如在x64的Linux上编译ARM64版本的Chromium用于嵌入式设备。这需要配置更复杂的工具链和sysroot。target_os linux target_cpu arm64 # 需要指定 sysroot通常通过 build/linux/sysroot_scripts/install-sysroot.py 获取 target_sysroot //build/linux/debian_bullseye_arm64-sysroot交叉编译的配置更为复杂需要确保所有依赖库都有对应的ARM64版本。7. 常见问题排查与实战技巧实录即使按照指南操作你也一定会遇到各种问题。这里记录了我踩过的一些坑和解决方案。7.1 网络问题与代码同步失败问题fetch或gclient sync过程中失败提示Failed to fetch或Connection reset。排查这几乎都是网络连接问题尤其是与Google服务器的连接不稳定。解决使用可靠的网络代理需在shell中配置http_proxy和https_proxy环境变量。注意这里指的是企业或学术机构内常见的HTTP代理用于加速访问境外开源站点绝对不涉及任何违规的网络访问行为。多次重试。gclient sync支持断点续传可以反复执行直到成功。如果某个仓库始终失败可以尝试手动进入该仓库目录如src/third_party/webrtc用git fetch和git reset手动操作。7.2 编译错误缺少头文件或库问题编译中途报错如fatal error: xxx.h: No such file or directory或cannot find -lxxx。排查这通常是系统依赖库没有安装完整。解决再次运行gclient runhooks确保二进制依赖已下载。根据错误信息使用apt search查找对应的开发包并安装。例如缺少libpulse-dev就安装它sudo apt install libpulse-dev。最彻底的方法是运行Chromium提供的完整依赖安装脚本如果之前跳过了# 在 src/ 目录下 ./build/install-build-deps.sh7.3 链接错误内存耗尽或段错误问题在链接阶段特别是创建chrome最终二进制时编译器进程被杀死或报出internal compiler error: Killed或segmentation fault。排查这几乎肯定是内存不足OOM。即使你的物理内存很大如果is_component_build false静态链接链接器如lld在合并所有目标文件时会消耗巨量内存。解决首选方案启用组件构建is_component_build true。这是为开发而生的模式。如果必须静态链接尝试增加系统的Swap空间。减少并行链接任务。在args.gn中设置use_thin_lto true如果使用LTO可能有助于降低内存峰值。升级到更高内存的机器。7.4 运行时错误无法启动或功能异常问题编译成功但./out/Default/chrome无法启动或启动后崩溃、页面渲染异常。排查检查依赖运行ldd ./out/Default/chrome | grep not found查看是否有缺失的动态库。自行编译的Chromium可能依赖一些非标准路径的库比如它自带的SwiftShader。检查沙箱Chromium的沙箱功能需要特定的内核配置和命名空间支持。如果启动时提示沙箱错误可以尝试添加--no-sandbox参数临时禁用仅用于测试正式使用有安全风险./out/Default/chrome --no-sandbox。查看日志运行./out/Default/chrome --enable-loggingstderr --v1可以将日志输出到终端有助于诊断问题。使用调试器用GDB启动gdb --args ./out/Default/chrome在崩溃时查看堆栈跟踪backtrace。7.5 磁盘空间管理技巧编译Chromium是磁盘空间“杀手”。除了准备大容量SSD还可以使用符号链接将out目录放在另一个容量更大的分区或硬盘上然后在src目录下创建指向它的符号链接ln -s /path/to/big/disk/out ./out。定期清理gn clean out/Default可以清理输出目录但保留args.gn配置。直接删除out/Default目录是最彻底的清理。使用ccache配置ccache可以缓存编译中间文件加速后续编译但需要额外磁盘空间做缓存。对于Chromium这种规模的项目ccache的收益非常明显。8. 从编译到贡献修改代码与提交成功编译只是第一步。真正的乐趣在于修改代码并可能向上游贡献。找到修改点假设你想修改地址栏的某个行为。你可以使用Chromium代码搜索https://source.chromium.org在线查找相关代码文件或者在本地代码库中用git grep搜索关键字。进行修改用你喜欢的编辑器如VSCode、CLion、Vim修改代码。编译测试进行增量编译然后运行你的自定义浏览器测试修改是否生效。运行相关测试确保你的修改没有破坏现有功能。运行与你修改模块相关的单元测试和浏览器测试。准备提交如果你认为修改有价值可以遵循Chromium的贡献流程在 https://bugs.chromium.org 上找到一个相关的Issue或创建一个新的。阅读贡献者指南签署贡献者许可协议CLA。使用git cl工具depot_tools的一部分创建代码审查Code Review请求。根据审查者的反馈修改代码直到通过合并。这个过程充满了挑战但也是深入理解一个超大型开源项目运作方式的绝佳机会。每一次编译都是与这个庞大系统的一次对话。当你看到自己的代码修改在浏览器中产生效果时那种成就感是无与伦比的。这不仅仅是编译了一个浏览器更是打开了一扇通往现代复杂软件系统核心的大门。