在 Windows 上构建 Firefox

本文档将帮助您在自己的计算机上设置构建 Firefox 的环境。设置可能需要一段时间 - 我们需要下载大量数据！即使在快速连接的情况下，这可能也需要 10 到 15 分钟的工作时间，分布在 1 到 2 个小时内。

如果您更愿意在虚拟机中为 Windows 构建 Firefox，您可能对 Microsoft 提供的 Windows 镜像 感兴趣。

系统要求

  • **内存：**至少 4GB RAM，建议 8GB 或以上。

  • **磁盘空间：**至少 40GB 的可用磁盘空间。

  • **操作系统：**Windows 10 或更高版本。建议将 Windows 更新完全更新到最新状态。有关更多信息，请参阅 支持的构建主机。

必需的安装

  • **Mercurial：**确保 hg 命令可在 PowerShell 中运行。如果未设置，请下载 Mercurial/TortoiseHg 并确保将 hg 目录添加到您的路径中。例如，这可能是 C:\Program Files\Mercurial 或 C:\Program Files\TortoiseHg。

  • **Python：**确保 python 和 pip3 命令可在 PowerShell 中运行。如果未设置，请下载 python 3.11，并将 python 目录 C:\Users\<user>\AppData\Local\Programs\Python\Python311 和 pip3 目录 C:\Users\<user>\AppData\Local\Programs\Python\Python311\Scripts 添加到您的路径中。

1. 安装 MozillaBuild

安装 MozillaBuild。

接受默认安装目录。Windows 可能会提示您“使用正确的设置重新安装”，您应该单击以接受。

在使用 Firefox 工具时，您需要在 MozillaBuild shell 中进行操作。您可以通过运行 C:\mozilla-build\start-shell.bat 来启动它（您可能希望为此文件创建一个快捷方式，以便更容易启动）。

注意

MozillaBuild shell 更像 Linux shell 而不是 Windows cmd。您可以在此处了解更多信息。

2. 引导 Firefox 源代码的副本

现在您的系统已准备就绪，我们可以下载源代码并让 Firefox 自动下载它所需的其余依赖项。以下命令将下载大量数据（Firefox 历史记录的数年！），然后引导您完成交互式设置过程。

# Using the C:\mozilla-build\start-shell.bat shell from step 1:
cd c:/
mkdir mozilla-source
cd mozilla-source
wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py

# To use Git as your VCS
python3 bootstrap.py --vcs=git

# To use Mercurial as your VCS
python3 bootstrap.py

注意

在运行 bootstrap.py 时，在选择源代码克隆的目标目录后，PowerShell 将会显示一个 UAC（用户帐户控制）提示。这是为了自动添加 Microsoft Defender 防病毒排除项。您应该在 UAC 提示中选择 Yes，否则您需要按照下面的一些手动步骤操作。

注意

要使用 git，您可以通过使用 vcs 参数运行引导脚本以“git”形式获取源代码

python3 bootstrap.py --vcs=git

这在后台使用了 Git Cinnabar。

选择构建类型

如果您没有修改 Firefox 后端，请选择 工件模式 选项之一。如果您正在为 Android 构建 Firefox，您还应该查看 GeckoView 贡献者指南。

确保防病毒排除

已知 Microsoft Defender 防病毒和一些第三方防病毒产品会大大降低构建时间，有时甚至会导致构建失败（由于“文件丢失”）。这通常是因为我们对众所周知的安全漏洞进行了测试，这些漏洞的代码示例被防病毒软件识别为威胁，从而自动隔离/损坏文件。

为避免这种情况，请将以下文件夹添加到您的第三方防病毒排除列表中

  • C:\mozilla-build 文件夹。

  • Firefox 代码所在的目录（可能是 C:\mozilla-source）。

  • %USERPROFILE%/.mozbuild 目录（可能是 C:\Users\<user>\.mozbuild）。

bootstrap.py 脚本尝试自动将上述文件夹添加到 Microsoft Defender 防病毒排除列表中。您应该检查它们是否已成功添加，但如果它们丢失，您需要 手动将排除项添加到 Microsoft Defender 防病毒中。

注意

如果您正在使用 Mercurial 并且您已经丢失了文件（您将在 hg status 中看到它们），您可以通过还原源代码树来将其恢复：hg update -C。

如果您正在使用 Git 并且您已经丢失了文件（您将在 git status 中看到它们），您可以通过丢弃源代码树中的更改来将其恢复：git restore .。

1. 构建

现在您的系统已引导，您应该能够构建了！

cd c:/mozilla-source/mozilla-unified
hg up -C central
./mach build

🎉 恭喜！您已经构建了自己的 Firefox！在成功构建后，您应该在终端中看到以下消息

Your build was successful!
To take your build for a test drive, run: |mach run|
For more information on what to do now, see https://firefox-source-docs.mozilla.ac.cn/setup/contributing_code.html

您现在可以使用 ./mach run 命令运行您本地构建的 Firefox！

如果您的构建失败，请参考 故障排除部分 中的步骤。

现在开始有趣的部分

是时候开始黑客攻击了！您应该加入我们在 Matrix 上的社区，在 简介频道 中打个招呼，并 找到一个要开始处理的错误。请参阅 Firefox 贡献者快速参考，了解如何测试您的更改、向 Mozilla 发送补丁、在本地更新您的源代码等等。

注意

如果您想从与 MozillaBuild 不同的命令行环境中与 Mach 进行交互，则可以使用 此处 描述的实验性支持。

故障排除

构建错误

如果您在尝试设置开发环境时遇到构建错误，请按照以下步骤操作

  1. 将整个构建错误复制到剪贴板

  2. 将此错误粘贴到 paste.mozilla.org 的文本区域中，并将“在一小时内过期”选项更改为“在一周内过期”。注意：获得帮助不需要一周时间，但最好让代码片段保留比预期更长的时间。

  3. 转到 简介频道 并寻求有关构建错误的帮助。请务必发布您创建的 paste.mozilla.org 代码片段的链接！

CLOBBER 文件已更新

这是一个常见的错误，并且往往在长时间处理错误时出现。如果您遇到此错误，则需要在运行 ./mach build 之前运行 ./mach clobber。运行 ./mach clobber 将删除以前的构建工件，以便从头开始重新构建。如果您使用的是工件构建，则表示下次构建将比平时稍长一些。但是，如果您使用的是非工件/完整构建，则下次构建将需要更长的时间才能完成。

MozillaBuild 过期

构建系统期望您使用最新的 MozillaBuild 版本。但是，MozillaBuild 不会自动更新。如果您遇到本地问题，可以通过 升级您的 MozillaBuild 来解决它们。

文件夹名称中的空格

如果 MozillaBuild 或 Firefox 源代码的路径包含**空格**或其他中断字符（例如加号、引号或元字符），则**Firefox 将无法构建**。Windows 用户名是路径中空格的常见原因，因此请确保您的 Windows 用户名不包含空格，否则 miniconda 在 fenix 构建期间将出现错误。Visual Studio 工具和 SDK 是例外 - 它们可以安装在包含空格的目录中。强烈建议您接受所有安装位置的默认设置。

PATH 中的引号

引号 (”) 在传递给 MozillaBuild 子 shell 时不会正确转换。由于它们通常不是必需的，因此您应该确保它们不在您的 PATH 环境变量中。

Python 无法在目录中找到文件

当达到路径长度限制时，Python 有时无法在目录中找到文件，即使根目录保持相对较短：C:\mozilla-source\mozilla-unified。这可以通过 打开 Windows 长路径 来解决。

PYTHON 环境变量

如果设置了 PYTHON，则构建可能会失败并出现以下错误：“The system cannot find the file specified。”确保您没有设置 PYTHON 环境变量。

Cygwin 干扰

如果您碰巧安装了 Cygwin，在构建 Firefox 时可能会错误地使用其工具。请确保 MozillaBuild 目录（位于 C:\mozilla-build\）在 PATH 环境变量中的位置优先于 Cygwin 目录。