Firefox 的编译架构在大型开源项目里算是最能折腾人的那一档。前几篇我们把构建系统、工具链、mozconfig 拆得七七八八，但真正动手的时候，你会发现绝大多数人的第一道坎根本不是写配置，而是两个看起来特别不起眼的步骤：源码拉取和 bootstrap 环境引导。我见过有人卡在hg clone断断续续下了三天，也见过有人在./mach bootstrap的交互选择界面直接懵掉——明明每一步都有提示，却不知道选完之后会发生什么。
这篇就顺着 Firefox 144+ 这个时间线的编译环境，把这两步从头到尾盘一遍：为什么一定要用 Mercurial 而不是 Git、bootstrap 底层到底在干什么、各个系统底下会碰到什么幺蛾子，以及我实测过的处理方案都在哪。如果你正准备从零编译一个自己的 Firefox，这篇能帮你省下至少一个周末。
1. 这两步为什么难倒一堆人：整体流程的定位与设计逻辑
1.1 Firefox 编译的第一步其实是“把大象装进冰箱”
很多第一次编译 Firefox 的朋友，上来就想直接搜mach build教程，结果发现文档里第一步永远是让你先拉源码，然后跑./mach bootstrap。这俩步骤在官方文档里被写得太轻描淡写了，好像就是两个命令的事，实际做起来却有大量隐含前提。
先说源码拉取。Firefox 不是一个小仓库，mozilla-central的完整 Mercurial 仓库包含着从 Netscape 时代一路演进过来的全部提交历史，单是.hg目录就能占到好几 GB。这和拉一个普通 GitHub 项目的体验完全是两码事。你以为执行完hg clone就万事大吉，实际上网络波动、磁盘空间、内存不足、甚至终端会话超时，任何一个环节出问题都会让整个过程前功尽弃。
再说 bootstrap。这个命令的名字听起来像是“自动装环境”，但它不是跑一下就完事。它会检测你的操作系统、包管理器、CPU 架构，然后再决定要用哪种方式安装 Rust、clang、Python 以及一大堆图形库依赖。不同发行版、不同版本的依赖包名称还不一样，光是把这些差异处理好，官方就写了几千行 Python 脚本。
所以先把预期放对：这两步是编译 Firefox 全流程里最容易让人放弃的地方，但也是最值得花时间搞懂原理的地方。
1.2 mach 和 bootstrap 为什么要设计成“源码必须先在机器上”
有个细节很有意思：./mach bootstrap这个命令必须在源码目录里才能运行。也就是说，你得先把上百 MB、乃至几个 GB 的源码拉下来，然后才能让自动化工具帮你装环境。为什么不反过来，先提供一个独立的系统环境安装脚本？
原因其实很朴素。Firefox 的构建系统演进这么多年，mach和源码之间的关系已经深度耦合了。mach本身是一个 Python 脚本，但它要读取源码目录里的配置文件、版本信息、第三方库的依赖声明，甚至部分 bootstrap 逻辑还要从源码里读取当前分支对应的依赖版本清单。如果把环境引导逻辑做成一个完全独立的安装器，那就得在不同版本之间同步维护一份额外的依赖清单，这对 Mozilla 这种每天都有大量提交的项目来说是不可接受的。
换句话说，你拉下来的不只是一份源码，还是一份带着“当前版本需要什么工具链”的说明书的源码。bootstrap 负责把这个说明书翻译成你系统上能用的包管理器命令。
1.3 这篇适合谁，读完能带走什么
如果你是第一次编译 Firefox，或者之前编译过但卡在环境准备阶段，这篇就是按你踩坑的顺序写的。我会把两种最常用的源码获取方式讲清楚，包括各自的优缺点、实测时间、磁盘占用，然后把 bootstrap 的交互过程拆开，告诉你每一步它到底在做什么，以及如果你手滑选错了选项，要怎么反悔。
如果你已经编译成功过，这篇里也有一部分值得看，比如增量更新的正确姿势、依赖版本冲突的排查表格、还有我在多台 Linux 发行版和 macOS 上实测过的坑。编译 Firefox 不是一锤子买卖，后续每次同步代码、调整工具链，都会用到这些经验。
2. 源码拉取：从仓库选型到落地全流程
2.1 官方仓库与可选方式：到底拉哪个
Firefox 的源代码主要托管在 Mozilla 自己的 Mercurial 服务器上，核心仓库地址是https://hg.mozilla.org/mozilla-central。在 GitHub 上也有一个mozilla/gecko-dev镜像，但官方文档和大部分构建工具都默认你使用 Mercurial，原因后面细说。
我们平时常用的仓库分支有这几个：
| 仓库 | 对应版本 | 更新频率 | 典型用途 |
|---|---|---|---|
mozilla-central | Nightly（每夜版） | 几乎每小时都有提交 | 学习源码、体验最新特性、给 Firefox 提 patch |
releases/mozilla-beta | Beta | 每 4 周一个大版本周期 | 编译一个稳定度适中的日常用浏览器 |
releases/mozilla-release | Release（正式版） | 每 4 周更新一次 | 编译接近官方正式版的体验 |
releases/mozilla-esr115等 | ESR（企业长期支持版） | 大版本周期较长 | 企业内部部署、需要长期维护的定制版 |
我的建议是，如果你只是为了学习编译流程，直接拉mozilla-central，不要犹豫。它是所有分支的源头，bootstrap 脚本对它支持得最好，而且你看到的代码就是 Firefox 团队每天在写的代码。如果你是想编译一个日常拿来用的浏览器，Beta 分支是更稳的选择。至于 ESR 系列，比如热词里经常出现的 Firefox 115 ESR，除非你有明确的企业场景，否则对个人学习来说没太大必要——它的构建配置和历史包袱更多，遇到问题的资料也相对少。
2.2 实操：hg clone 完整流程与时间空间预估
在开始之前，先确认三件事：网络稳定、磁盘空间足够、Python 3 可用。Mercurial 本身可以用系统包管理器安装，也可以直接用 pip 装：
# Ubuntu/Debian sudo apt install mercurial # macOS brew install mercurial # 其他发行版请用对应的包管理器，也可以在虚拟环境里用 pip pip install mercurial确认hg --version能跑通之后，找一个磁盘空间足够的分区，执行：
hg clone https://hg.mozilla.org/mozilla-central firefox-source这里firefox-source是你本地目录的名字，可以随便起，但建议不要用带空格和中文的路径，后面构建时会有各种脚本对路径做拼接，路径越简单越省心。
实测下来，在带宽正常、网络状况较好的环境下，完整 clone 一次mozilla-central大约需要 30 到 60 分钟，脚本会先下载全部提交历史，然后 checkout 出最新的工作目录。如果你的网络环境一般，耗时几个小时也很正常。同时候网络波动会导致连接中断，所以一定要有心理准备。
磁盘空间方面，clone 完成后源码目录本身通常在 5 GB 到 8 GB 之间，其中.hg历史目录占了大头。但这只是开始，后面构建会产生另一个存放编译产物的obj-*目录，动辄 20 GB 到 40 GB。也就是说，如果只是为了编译一次 Firefox，磁盘至少预留 50 GB 才算稳妥。我自己的习惯是单独给 Firefox 编译准备一个分区，避免把系统盘塞满。
clone 完成后，可以用这几条命令做基础验证：
cd firefox-source hg id hg log -l 1hg id能看到当前 checkout 的版本标识，hg log -l 1能确认最新的提交信息。如果你看到一串类似abcdef0+的输出，说明工作目录比远程仓库领先一个未提交的变更状态，属于正常现象。
2.3 版本选择：Nightly / Beta / Release / ESR 的取舍
如果你已经在心里定了用哪个分支，这一节可以快速扫过。但如果还在纠结，我给你一个比较务实的决策路径。
先看目的。只是想跑通编译流程、学习构建系统原理，选mozilla-central，没有第二个选项。理由很简单：官方文档、博客、构建机器人默认都是基于这个分支，你在搜索引擎上能找到的报错解决方案，绝大多数对应的就是这个分支的状态。
想编译一个稳定到可以日常用的版本，选 Beta。Beta 分支的代码比正式版新一点，但因为经过了 nightly 阶段的验证，明显的编译问题已经被修掉了。我曾在 Ubuntu 上编译过 Beta 分支并连续用了一周，除了启动时偶尔出现 webrender 的小问题，整体体验和官方版没太大差别。
至于 ESR，它的编译坑在于生命周期长、老代码兼容逻辑多。你可能会在依赖版本上遇到和当前系统不匹配的情况，比如旧版 ESR 需要老版本的 autoconf，这在新系统上不一定好找。所以我一般只建议两种人碰 ESR：企业定制需求的开发者，或者想研究 Firefox 长期维护分支的源码差异的爱好者。
2.4 存量环境下的增量更新与打包下载
源码拉好之后并不是一劳永逸。Firefox 的迭代速度极快，你今天拉的主干，过几天就落后了几百个 commit。想跟进上游，不需要重新 clone，直接增量更新：
hg pull hg updatehg pull会把远程仓库的新提交拉到你本地的.hg历史里，hg update则把工作目录的文件更新到最新状态。这两个命令分开跑的好处是，你可以先 pull 完，检查一下远程有没有破坏性的变更，再决定要不要 update。
如果你的网络确实差到连 clone 都很难完成，还有一个备选方案：从官方下载源码快照包。在浏览器里打开https://hg.mozilla.org/mozilla-central/archive/tip.zip，会得到一个包含最新源码的 zip 包。这种方式不需要安装 Mercurial，解压就能用，但代价是你拿不到完整历史，以后没法用hg pull做增量更新，只能靠每次下载新快照来同步。
我的个人建议是：如果只是临时看看源码，用 zip 快照没问题；如果打算长期跟进编译，哪怕第一次 clone 再慢，也值得硬着头皮把完整的 Mercurial 仓库拉下来。增量更新的效率优势，会在你第二次同步代码时立刻体现出来。
3. bootstrap 环境引导：自动化的背后逻辑与实际操作
3.1 bootstrap 到底干了什么
你把源码弄到本地之后，接下来要面对的就是./mach bootstrap。很多教程对这一步的描述是“自动安装构建依赖”，但真正跑过的人都知道，它会做远比“安装依赖”四个字多得多的操作。
bootstrap 的核心职责有三块。第一，识别当前系统。同样的依赖，在 Ubuntu 上叫libgtk-3-dev，在 Fedora 上叫gtk3-devel，在 Arch 上叫gtk3。如果让你自己查文档手动装，每一行都得对着官方 wiki 核对，bootstrap 用 Python 脚本把不同发行版的包名差异全部解决了。
第二，确认你想要构建什么。Firefox 构建体系里有很多不同的产物，最常用的是桌面版 Firefox，但你也可以选择只构建 GeckoView（Android 上的浏览器引擎）、构建 Firefox for Android，甚至只构建某些单元测试工具。bootstrap 会先问你要构建哪个目标，再根据目标去装不同的依赖集合。
第三，处理工具链的特殊安装方式。这里的“特殊”指的是 Rust。Firefox 对 Rust 的版本有明确要求，很多系统的包管理器自带 Rust 版本过旧。bootstrap 会检测到这一点，然后自动通过 rustup 安装 Mozilla 指定的 Rust 工具链版本。这比你自己折腾rustup toolchain install要省心得多。
3.2 实操：./mach bootstrap 的完整交互过程
在源码目录里直接运行：
./mach bootstrap第一次运行时，它会先检查你机器上有哪些依赖缺失，然后弹出一个交互式菜单，一般长这样：
Please choose the version of Firefox you want to build: 1. Firefox for Desktop 2. Firefox for Android 3. GeckoView for Android这里直接选 1 就行。除非你要做 Android 开发，否则不要选 2 和 3，后面两个会额外要求安装 Android SDK 和 NDK，体积大又慢。
接下来，bootstrap 会告诉你它准备调用系统的包管理器安装一系列依赖，并提示你可能需要输入 sudo 密码。这里注意，一定要仔细看它列出来的包列表。如果列表里有你没见过的包，不要慌，那基本是 Firefox 运行所需的内存数据分析工具、图形栈开发库之类的依赖，正常现象。
确认之后，bootstrap 会真正开始安装。在 Ubuntu 上，你会看到大量apt-get install的输出；在 macOS 上，它调用的是 Homebrew；在 Fedora 上是 dnf；在 Arch 上是 pacman。安装过程中如果某一步失败了，bootstrap 通常会直接抛错退出，并告诉你哪个包安装失败。
安装完系统依赖后，它会继续处理 Rust 工具链。这一步动静同样不小，因为要下载 Rust 编译器和配套组件，有时还需要等上一阵子。所有步骤完成后，bootstrap 会输出类似下面的内容：
Bootstrap complete! You can now run: ./mach build看到这个提示，说明环境引导已经很顺利了。但先别急着 build，继续看后面的验证环节。
3.3 各系统差异：apt / dnf / pacman / brew 的细节
虽然 bootstrap 的目标是“完全自动化”，但不同系统上跑起来的表现区别很大，最好心里有数。
Ubuntu/Debian 系是我觉得最顺的，毕竟 Firefox 团队内部和 CI 大量使用 Debian/Ubuntu 环境，依赖包名覆盖比较全。实测在 Ubuntu 22.04 和 24.04 上跑 bootstrap，除了libdbus-glib-1-dev这种老包在 24.04 上已经被移除需要手动确认之外，其他基本没出过问题。
Fedora/RHEL 系也还行，但如果你用的是 Fedora 的新版本，有可能会遇到mock或dnf插件相关的提示，那是因为包管理器默认配置和 bootstrap 脚本里的预期不太一样。这种情况一般按提示升级dnf或安装dnf-plugins-core就能解决。
Arch 系需要额外注意。Arch 的滚动更新导致依赖版本通常很新，bootstrap 检查版本时偶尔会因为“版本过新”给出警告。别慌，Firefox 对编译器版本的容忍度比 Rust 高很多，clang 新一点问题不大。真要不行，可以在 mozconfig 里指定具体工具链版本。
macOS 上走的是 Homebrew，由于 macOS 本身的文件系统大小写敏感性、Command Line Tools 版本差异，偶尔会遇到路径问题。bootstrap 一般会给你提示，建议严格按照它推荐的步骤处理。
Windows 是最特殊的，它不走系统包管理器，而是使用 Mozilla 自带的 MozillaBuild 套件。bootstrap 在 Windows 上的首要任务是帮你下载解压 MozillaBuild，再引导你在那个环境里跑构建。Windows 编译的坑比 Linux 多一个数量级，如果不是必须，我还是建议用 WSL 或者虚拟机装 Linux 来编译。
3.4 关键的版本一致性：为什么不能随便装最新版依赖
bootstrap 装完环境之后，很多人会手痒地升级一下系统里的 Rust 或者 clang，觉得“新版肯定比旧版好”。这个想法在编译 Firefox 这件事上是错的。
Firefox 对工具链版本的依赖非常敏感，尤其是 Rust。Gecko 的代码用到了大量 Rust 的 unstable 特性，不同版本之间的内部表示和编译器行为变化，会导致编译失败或者运行时崩溃。Mozilla 在源码树里维护了一份工具链版本清单，bootstrap 按清单安装的版本，是经过大量测试的组合。你如果手动升级 Rust 到更新的版本，虽然大概率也能编过，但一旦遇到奇怪的链接错误或运行不稳定，排查起来会非常痛苦。
还有一个典型问题是 clang 版本过旧。部分长期不更新的发行版，系统自带的 clang 连 Firefox 支持的最低版本都达不到。bootstrap 遇到这种情况通常会提示你安装新版 clang，或者建议通过 Mozilla 提供的工具链缓存机制下载预编译的 clang。不要图省事跳过这个检查，configure 阶段对 clang 版本有硬性要求，跳过只会让报错集中爆发在后面。
核心原则就是一句话：让 bootstrap 管理工具链版本，不要自作主张。
4. 常见问题与排查技巧实录
4.1 网络中断、TUI 读取失败与重试策略
源码拉取最烦人的问题就是网络中断。Mercurial 的 clone 过程如果断线，通常会直接报abort: stream ended之类的错误。此时需要删除未完成的目录重新运行，但我实测下来，重建的耗时往往会比第一次短一些，因为部分数据可能已经缓存在本地了。所以不要因为一次失败就泄气，多试几次很正常。
如果网络状况实在差到没法完整 clone，可以在浏览器或下载工具里先获取官方 zip 快照包，再把源码放到本地，后续用补丁文件的方式同步上游。这个方法虽然失去了增量更新能力，但总比一直拉不下来强。
另外要提醒一个交互环境的坑。有些人在 SSH 会话或者 CI 环境里运行./mach bootstrap，会看到类似下面这种错误：
error: account/read failed during tui bootstrap: account/read failed: ...这类报错的核心原因是：bootstrap 的交互菜单（TUI）无法从当前终端读取输入。解决办法很简单，换一个真实的本地终端运行，或者确保当前 shell 支持交互式输入。千万不要在非交互环境里硬跑，因为它需要你在菜单中选择构建目标并确认安装包，没人输入它就会一直报错。
4.2 磁盘空间不足与目录规划
Firefox 编译对磁盘空间的消耗超乎很多人想象。我之前说过源码目录 5 到 8 GB，构建产物目录 20 到 40 GB，这还不包括 bootstrap 过程中下载的 Rust 工具链、clang 工具链缓存等。如果你只有一块 40 GB 的根分区，几乎可以断定会在构建中途因磁盘写满而失败。
提前用df -h检查磁盘情况，给源码和构建产物预留足够空间。如果实在紧张，可以在 mozconfig 里把编译产物目录指向另一个分区。这个方法在 5.2 节会给出具体写法。
还有一个小细节：不要为了省空间把源码放在/tmp或者 tmpfs 挂载的目录里。这类目录在重启后会被清空，而且内存盘空间有限，编译过程中很容易写满。
4.3 依赖冲突与工具链版本覆盖
我在 Ubuntu 上遇到过的最典型的依赖冲突是系统自带 Rust 和 bootstrap 要求的 Rust 版本不一致。Ubuntu 软件源里的 rustc 往往落后 Mozilla 要求的版本半年以上，bootstrap 检测后会选择通过 rustup 安装一个新版 Rust，但它不会主动卸载系统的 rustc。如果你在运行 bootstrap 之前手动添加了~/.cargo/bin到PATH，系统可能在 configure 阶段混用两个 Rust 版本，导致莫名其妙的编译错误。
我的建议是：在跑 bootstrap 前，如果系统里有 rustc，可以先卸载或者暂时移出PATH，让 bootstrap 全权管理 Rust 工具链。等 bootstrap 完成后，再用rustup show检查默认工具链是不是 Mozilla 要求的那一个。
clang 的冲突也很常见。某些发行版会在系统默认路径里同时存在 clang 和 gcc，Firefox 是明确指定要 clang 的，如果 configure 阶段检测到了不正确版本，会直接报错。这时候需要把 clang 版本信息通过环境变量传给构建系统，或者干脆在 mozconfig 里写清楚。
4.4 常见错误速查表
我把实际踩过的坑按现象、原因、解决方案整理成了一张表，遇到问题可以直接对号入座。
| 报错现象 | 可能原因 | 解决方案 |
|---|---|---|
hg clone abort: stream ended | 网络中断或服务器连接超时 | 删除未完成目录重新 clone；或下载官方 zip 快照 |
bootstrap TUI read failed | 在非交互 shell 里运行引导菜单 | 用真实终端运行；确保 shell 支持读取输入 |
configure: clang version too old | 系统 clang 不满足最低版本要求 | 安装新版 clang，或通过 Mozilla 工具链缓存下载预编译 clang |
cargo: command not found | Rust 工具链没有加入 PATH | 确认 rustup 安装路径，重启 shell 或手动添加~/.cargo/bin |
error: failed to run custom build command | 依赖库版本不匹配 | 查看具体报错里缺哪个库，顺着安装对应-dev包 |
disk full或No space left on device | 构建产物目录写满 | 清理旧构建目录，或用 MOZ_OBJDIR 指向其他磁盘 |
firefox 启动后很快闪退 | 构建选项和运行时库不匹配 | 检查动态库依赖，ldd ./obj-*/dist/bin/firefox看缺失项 |
这张表没有覆盖所有情况，但已经能解决八成环境引导阶段的问题了。
5. 环境引导完成之后：第一次构建前的最终检查
5.1 验证源与 mach 自检
bootstrap 全流程跑完，先别急着执行./mach build，有几个快速检查能帮你省掉后面的大麻烦。
首先是验证源码树的状态。运行hg id，确认你 checkout 的确实是预期版本。如果你之前拉的是mozilla-central，这里显示的应该是default分支的最新节点。
然后是mach自检。运行：
./mach environment这条命令会读取当前源码树的配置，并打印出构建系统即将使用的 Python 路径、编译器路径、目标架构等信息，相当于给你一份“环境体检报告”。如果报告里出现could not find clang或者 Python 版本不对的提示，回去检查 bootstrap 的输出，不要直接 build。
最后是检查~/.mozbuild目录。bootstrap 会在你的用户目录下生成.mozbuild，里面存放着下载下来的工具链、缓存、日志。这个目录偶尔会累积大量缓存，我建议第一次构建之前先看看它有没有异常的超大文件，如果一切正常就继续。
5.2 mozconfig 模板与 ccache 配置
mach build默认会读取源码根目录里的mozconfig文件，你可以把它理解为 Firefox 的构建配置文件。对于第一次编译，我推荐一个极简模板：
# 编译产物目录单独放，避免和源码混在一起 mk_add_options MOZ_OBJDIR=./obj-ff # 构建桌面版 Firefox ac_add_options --enable-application=browser # 编译正式版代码路径，减少调试信息体积 ac_add_options --enable-release # 关闭测试套件，初学阶段用不到 ac_add_options --disable-tests # 显式指定编译器 export CC=clang export CXX=clang++这个模板有几个关键选择值得说清楚。第一，MOZ_OBJDIR指定构建产物目录，这样清理构建结果时直接删整个obj-ff目录就行，不会污染源码树。第二，--enable-release会去掉很多调试符号和断言代码，编译时间更短，生成的浏览器体积也更小。第三，--disable-tests会跳过编译一堆测试二进制，能省不少时间和磁盘。
如果你想给后续增量编译提速，还可以加上：
mk_add_options MOZ_MAKE_FLAGS="-j$(nproc)" export CCACHE=1ccache是编译器缓存，第一次构建时作用不大，但之后每次增量同步代码再重新编译，能省下大量重复编译时间。这个属于我自己每天编译时必开的选项，强烈建议一开始就配好。
5.3 虚拟机/容器环境里编译的额外注意事项
如果你和我一样习惯在虚拟机里编译，有几个环境相关的点需要提前处理，不然会在编译中半路崩溃。
首先是内存。Firefox 构建并发度高，建议至少给虚拟机分配 8 GB 内存，16 GB 更舒服。如果内存不够，链接阶段很容易触发 OOM，表现是mach build进程被系统直接杀掉，终端看不出明确的报错。
其次是 CPU 核数。-j$(nproc)会让编译任务数等于虚拟机里看到的 CPU 核数。如果你的宿主机器核数很多，但给虚拟机分配的核心数有限，nproc会如实反映虚拟机的核数，不用手动调。但如果宿主机器本身内存紧张，建议不要开满并发，用-j4或者-j8更稳。
还有网络。虚拟机的 NAT 模式通常可以访问外网，但如果你发现 Ubuntu 虚拟机里连外网都出问题，比如“vmware ubuntu firefox 无法上网”这类情况，先检查虚拟网络适配器的模式，再检查系统里有没有残留的静态 DNS 配置。源码拉取阶段对网络要求高，网络不通会引发一连串后续问题。
容器环境类似，但不建议用 Docker 直接搞 Firefox 编译，因为容器里缺少完整的 init 系统和图形库，bootstrap 阶段就会报错。如果非要用容器，可以考虑挂载宿主机的 X11 socket，但那已经是另一个深度话题了，初学没必要碰。
5.4 最后的一句个人体会
源码拉取和 bootstrap 引导这两步，看起来只是“准备工作”，其实它们决定了整个编译流程的成败和心情。我在实际使用中最深的体会是：千万不要觉得跑完./mach bootstrap就算环境搞定了，真正的环境验证要看./mach environment的输出是否干净、第一次./mach configure能否顺利通过。
我的固定习惯是：clone 完成当天就立刻跑 bootstrap，让机器有一个晚上慢慢下载和安装依赖；第二天早上起来先./mach configure，确认通过之后再跑./mach build。这样把“环境准备”和“实际构建”拆开，每次遇到报错都能更准确地定位问题。这个流程我重复了无数遍，至少可以帮你避开一批我在凌晨三点排查过的弱智问题。
