chrome浏览器二次开发和chromium源码编译官方教程中文版

chrome浏览器二次开发和chromium源码编译官方教程中文版(windows)

其他平台的说明请参见 获取代码 页面中的链接。

谷歌员工专用说明

您是 Google 员工吗？请改为查看 go/building-chrome-win。

系统要求

• 一台 x86-64 架构的机器，至少 8GB 内存，建议使用超过 16GB 内存。
• 至少 100GB 的可用磁盘空间，且硬盘必须为 NTFS 格式。FAT32 格式无法使用，因为某些 Git 包文件大于 4GB。
• 下文所述版本的 Visual Studio。
• Windows 10 或更高版本。

设置 Windows 环境

Visual Studio

Chromium 构建需要 Visual Studio 2022（版本 ≥17.0.0）。Visual Studio 也可用于调试 Chromium。

虽然使用的是 clang-cl 编译器，但仍然需要 Visual Studio 的头文件、库和部分工具。Visual Studio Community Edition 也可以使用，只要它的许可证适用于您即可。必须安装 “使用 C++ 的桌面开发” 组件和 “MFC/ATL 支持” 子组件。可以通过命令行传递以下参数给 Visual Studio 安装器来完成安装（ARM64 安装说明见下）：

$ PATH_TO_INSTALLER.EXE ^
--add Microsoft.VisualStudio.Workload.NativeDesktop ^
--add Microsoft.VisualStudio.Component.VC.ATLMFC ^
--includeRecommended

如果您希望构建 ARM64 Win32，则还需要一些额外参数。完整参数如下：

$ PATH_TO_INSTALLER.EXE ^
--add Microsoft.VisualStudio.Workload.NativeDesktop ^
--add Microsoft.VisualStudio.Component.VC.ATLMFC ^
--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^
--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^
--includeRecommended

必须安装的组件：

• Windows 11 SDK，版本 10.0.26100.3323。可以单独安装，也可以在 Visual Studio 安装器中勾选相应选项安装。
• （Windows 11）SDK 调试工具，版本 10.0.26100.3323 或更高。Chrome 使用了大页面 PDB 文件（支持超过 4 GiB 的 PDB 文件），需要这个版本的调试工具。如果当前 SDK 安装中未包含调试工具，可以按以下路径安装：
  控制面板 -> 程序和功能 -> Windows 软件开发工具包 [版本] -> 更改 -> Windows 调试工具。
  如果是在 ARM64 Windows 上构建 Chromium，无论构建的是 x64 还是 ARM64，都需要从另一台机器上手动复制 Debuggers\x64 目录，因为该目录不会在 ARM64 上自动安装，但却是必要的。

警告： 在较旧版本的 Windows（1909 或更早）中，使用 26100 SDK 时，dawn 或相关组件可能因 D3D 相关错误而失败。这是因为新 SDK 中的 d3dcompiler_47.dll 文件尝试动态链接某些旧系统中默认缺失的 Universal C Runtime（UCRT）版本。如果遇到此类错误，可以选择更新系统的 UCRT，或者安装 22621 SDK，并使用其中的 d3dcompiler_47.dll 文件（该版本使用静态链接的 UCRT）。

此问题也可能表现为 DLL 加载失败，并出现 __CxxFrameHandler4 无法加载的错误。

安装 Git

安装 Git

如果你以前没有直接安装过 git，可以从 Git 官网下载最新版本的 Git for Windows 独立安装程序：
https://git-scm.com/download/win

有关 Git for Windows（它是一个独立于 Git 的项目）的更多信息，请访问：
https://gitforwindows.org

注意： 如果你是 Google 员工，请查看 go/building-chrome-win 上的 Git 安装说明。

更新 Git

注意： 本节内容是关于更新直接安装的 git，因为 depot_tools 很快将不再捆绑 git。

更新到最新版本的方法取决于你当前安装的版本。首先，在 cmd.exe 命令行窗口中运行以下命令查看版本：

$ git version

当前版本	如何更新到最新版
2.14.1 或更早	需要手动卸载 Git，然后按照上面的安装 Git说明重新安装
2.14.2 到 2.16.1	在 cmd.exe 中运行：git update
2.16.1(2) 及更高版本	在 cmd.exe 中运行：git update-git-for-windows

安装 depot_tools

在命令行窗口中，切换到你希望存放 depot_tools 的目录，并克隆 depot_tools 仓库。例如，如果你想克隆到 C:\src\depot_tools：

$ cd C:\src
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

将 depot_tools 添加到系统 PATH 的开头位置（必须位于任何 Python 安装目录之前。注意环境变量名称不区分大小写）。

• 假设你将仓库克隆到了 C:\src\depot_tools，打开：
  控制面板 → 系统和安全 → 系统

• 选择要编辑的 PATH 变量：

  • 如果你拥有管理员权限，可以编辑 系统级 PATH。点击“高级系统设置” → “环境变量”，在“系统变量”中选择 Path 进行编辑。
  • 如果你没有管理员权限，可以编辑你的 用户级 PATH。搜索“为你的账户编辑环境变量”，在“用户变量”中选择 Path 进行编辑。
• 修改 PATH 变量，将 C:\src\depot_tools 添加到最前面（至少要在任何已有的 Python 路径前面）。
  注意： 如果你只能修改用户级 PATH，而系统 PATH 中存在 Python 路径，那么你可能会遇到问题。

此外，还需要以同样的方式添加一个名为 DEPOT_TOOLS_WIN_TOOLCHAIN 的环境变量，并将其值设置为 0，表示 depot_tools 使用本地安装的 Visual Studio（默认情况下它会尝试使用 Google 内部版本）。

你可能还需要设置一个名为 vs2022_install 的变量，指定你的 Visual Studio 2022 安装路径，例如：

set vs2022_install=C:\Program Files\Microsoft Visual Studio\2022\Professional

在 cmd.exe 命令行窗口中运行：

$ gclient

首次运行时，gclient 会安装所有在 Windows 上使用代码所需的内容，包括 msysgit 和 python。

• 如果你不是从 cmd.exe 运行 gclient（例如使用 cygwin 或 PowerShell），虽然看起来运行正常，但 msysgit、python 以及其他工具可能不会被正确安装。
• 如果你在第一次运行 gclient 时遇到文件系统相关的奇怪错误，建议关闭 Windows 索引功能。

检查 Python 安装

运行 gclient 之后，打开命令提示符，输入以下命令确认 depot_tools 中的 python3.bat 优先于系统中其他 python3.exe：

where python3

如果没有优先设置，使用 gn 构建时可能会导致过度构建（overbuilding），详见 crbug.com/611087。

App 执行别名 可能与系统中其他 Python 安装冲突。建议禁用 “App Installer” 创建的 python.exe 和 python3.exe 别名，方法如下：

1. 打开控制面板中的 App execution aliases。
2. 找到 python.exe 和 python3.exe，取消勾选“App Installer”旁边的选项。

获取代码

首先配置 Git：

$ git config --global user.name "My Name"
$ git config --global user.email "[e-mail]"
$ git config --global core.autocrlf false
$ git config --global core.filemode false
$ git config --global core.preloadindex true
$ git config --global core.fscache true
$ git config --global branch.autosetuprebase always

虽然不是强制要求，但建议启用长路径支持（支持超过 Windows 的 MAX_PATH 限制）：

git config --global core.longpaths true

创建一个用于检出 Chromium 代码的目录并进入该目录。该目录名称和路径可以自定义，只要路径中不包含空格。不过，Google 员工若将其放在 C:\src\ 下会有性能优势（参考：为什么构建变慢？）。

$ mkdir chromium && cd chromium

使用 depot_tools 中的 fetch 工具来获取代码和所有依赖：

$ fetch chromium

如果你不需要完整的提交历史，可以加 --no-history 参数加快速度：

$ fetch --no-history chromium

注意：即使在快速网络环境下也可能耗时超过一小时，慢速网络可能需要数小时。建议关闭电脑的睡眠和休眠功能以避免中断。如遇到获取子仓库失败的错误，可以重新开始，也可以进入 chromium/src 目录执行以下命令尝试修复：

$ gclient sync

fetch 完成后，会生成一个 .gclient 文件和一个名为 src 的目录。之后的命令都假设你已进入该 src 目录：

$ cd src

可选： 若希望构建过程中访问某些 Google 服务，可以配置 API 密钥，但大多数开发和测试场景下不需要。

---

设置构建环境

Chromium 使用 Ninja 作为构建工具，配合 GN 生成 .ninja 文件。你可以创建多个构建目录，适配不同配置：

$ gn gen out\Default

说明：

• 每个构建目录只需运行一次该命令，Ninja 会根据需要更新构建文件。
• 可以将 Default 替换为其他名称，但必须是 out 的子目录。
• 如需了解发布构建、使用其他 VS 版本等配置，请查看 GN 构建配置。
• 默认生成的是一个调试版、组件化构建（debug component build）。

查看更多 GN 信息可运行：

gn help

或参考 GN 快速入门。

加快构建速度的建议

• 将构建目录从杀毒软件和 Windows 索引中排除。
• 构建目录应位于高速磁盘（如 SSD）上。
• CPU 核心越多越好（20+ 并不算多），内存越多越好（64 GB 也不夸张）。

建议使用以下 GN 参数优化构建速度，可在运行 gn gen 时添加 --args，或使用 gn args out\Default 进入编辑器设置：

gn gen out\Default --args="is_component_build=true enable_nacl=false blink_symbol_level=0 v8_symbol_level=0 symbol_level=1"

各参数含义如下：

• is_component_build = true：使用更多但较小的 DLL，可能避免频繁 relink chrome.dll。
• enable_nacl = false：禁用 Native Client，本地构建通常不需要。
• target_cpu = "x86"：生成 x86 构建，速度可能稍快。但需搭配 enable_nacl=false，否则构建时间反而更长。
• blink_symbol_level = 0：关闭 Blink 的源码调试信息，适用于不调试 Blink 的情况。
• v8_symbol_level = 0：关闭 V8 的源码调试信息，适用于不调试 V8 的情况。

• symbol_level = 1 或 0：加快链接速度：

  • symbol_level = 1：保留源码行号，无变量类型信息。

  • symbol_level = 0：不保留源码调试信息，但函数名可用于堆栈追踪。

    更改该参数需重新编译所有内容。

使用 Ninja 构建时，指定 chrome 作为目标可避免构建所有测试目标：

$ autoninja -C out\Default chrome

---

使用 Reclient

此外，Google 员工应使用 Reclient，这是一种分布式编译系统。相关的 gn 参数为：

• use_remoteexec = true

Google 员工可以访问 go/building-chrome-win#setup-remote-execution 获取更多信息。对于外部贡献者，Reclient 不支持 Windows 构建。

使用 SCCACHE

你也许可以通过启用以下参数，使用 sccache 来加速构建过程：

• cc_wrapper = "sccache" —— 假设 sccache 可执行文件已加入 %PATH% 中

为什么构建很慢？

构建速度慢可能由多种原因引起，Windows Defender 减缓进程启动是一个常见问题。你是否确保整个 Chromium 的 src 目录已被排除在杀毒扫描之外（在 Google 的设备上，这意味着将其放在某个磁盘根目录下的 src 目录中）？你是否尝试了上面列出的不同设置，包括不同的链接设置和 -j 参数？你是否在 chromium-dev 邮件列表中询问过，看看你的构建是否比同配置的机器预期更慢？

如果你怀疑 Defender 导致构建变慢，可以使用微软的 Microsoft Defender Antivirus 性能分析器 进行深入分析。

接下来是收集数据。如果你设置环境变量 NINJA_SUMMARIZE_BUILD 为 1，autoninja 将执行三件事。首先，它会设置 NINJA_STATUS 环境变量，使得 ninja 在构建过程中输出更多信息，包括当前运行的构建进程数、已完成的构建步骤数、每秒完成的构建步骤数以及构建已运行的时间，如下所示：

$ set NINJA_SUMMARIZE_BUILD=1
$ autoninja -C out\Default base
ninja: Entering directory `out\Default'
[1 processes, 86/86 @ 2.7/s : 31.785s ] LINK(DLL) base.dll base.dll.lib base.dll.pdb

这样可以立刻发现是否进程创建过慢，并快速判断构建是否比平常慢。

此外，设置 NINJA_SUMMARIZE_BUILD=1 后，autoninja 会在构建完成时打印构建性能摘要，显示最慢的构建步骤和构建步骤类型，如下：

$ set NINJA_SUMMARIZE_BUILD=1
$ autoninja -C out\Default base
最长的构建步骤：
       0.1 加权秒 来构建 obj/base/base/trace_log.obj（耗时 6.7 秒）
       0.2 加权秒 来构建 nasm.exe, nasm.exe.pdb（耗时 0.2 秒）
       0.3 加权秒 来构建 obj/base/base/win_util.obj（耗时 12.4 秒）
       1.2 加权秒 来构建 base.dll, base.dll.lib（耗时 1.2 秒）
各类构建步骤耗时：
       0.0 秒加权时间来生成 6 个 .lib 文件（总耗时 0.3 秒）
       0.1 秒加权时间来生成 25 个 .stamp 文件（总耗时 1.2 秒）
       0.2 秒加权时间来生成 20 个 .o 文件（总耗时 2.8 秒）
       1.7 秒加权时间来生成 4 个 PEFile（链接）文件（总耗时 2.0 秒）
      23.9 秒加权时间来生成 770 个 .obj 文件（总耗时 974.8 秒）
26.1 秒加权时间（总耗时 982.9 秒，37.7 倍并行度）
完成了 839 个构建步骤，平均每秒 32.17 个

“加权”时间是每个构建步骤的耗时除以并行运行的任务数量。这很好地反映了一个步骤的“重要性”。如果链接过程是串行执行的，那么其加权时间与实际耗时接近；而一个与 999 个其他编译并行运行的编译过程，其加权时间会非常小。

你也可以在构建后手动运行脚本来生成这些报告：

$ python depot_tools\post_build_ninja_summary.py -C out\Default

最后，设置 NINJA_SUMMARIZE_BUILD=1 会让 autoninja 向 ninja 传递 -d stats 参数，让它报告自身开销，这在分析由于 clang-cl 不在排除目录下导致杀毒软件干扰、进程创建缓慢（在 StartEdge 指标中体现）等问题时非常有用：

$ set NINJA_SUMMARIZE_BUILD=1
$ autoninja -C out\Default base
metric                  count   avg (us)        total (ms)
.ninja parse            3555    1539.4          5472.6
canonicalize str        1383032 0.0             12.7
canonicalize path       1402349 0.0             11.2
lookup node             1398245 0.0             8.1
.ninja_log load         2       118.0           0.2
.ninja_deps load        2       67.5            0.1
node stat               2516    29.6            74.4
depfile load            2       1132.0          2.3
StartEdge               88      3508.1          308.7
FinishCommand           87      1670.9          145.4
CLParser::Parse         45      1889.1          85.0

你还可以使用 ninjatracing 生成可视化的构建性能报告。它会将 .ninja_log 文件转换为 .json 文件，可通过 chrome://tracing 加载查看：

$ python ninjatracing out\Default\.ninja_log >build.json

编译 Chromium

使用 Ninja 编译 Chromium（“chrome”目标），命令如下：

$ autoninja -C out\Default chrome

autoninja 是一个封装工具，会自动为 ninja 提供最优参数。

你可以通过运行 gn ls out\Default 来获取所有其他构建目标的列表。要编译某个目标，只需将 GN 标签传给 Ninja，不需要前缀的 //（例如，对于 //chrome/test:unit_tests，使用 autoninja -C out\Default chrome/test:unit_tests）。

编译单个文件

Ninja 支持一种特殊的 语法 ^，可以通过指定源文件来编译单个目标文件。例如，ninja -C out/Default ../../base/logging.cc^ 会编译出 obj/base/base/logging.o。

使用 autoninja 时，需要加上 ^^ 来保留结尾的 ^：

$ autoninja -C out\Default ..\..\base\logging.cc^^

除了支持 foo.cc^^，Siso 也支持 foo.h^^ 语法来编译对应的 foo.o（如果存在的话）。

如果你使用 bash shell，可以使用下面的脚本来简化编译过程：

#!/bin/sh
files=("${@/#/..\/..\/}")
autoninja -C out/Default ${files[@]/%/^^}

该脚本假设你在 src 目录中运行，输出目录为 out/Default；它调用 autoninja 来编译所有给定文件。若你将该脚本放入 $PATH 并命名为 compile，可以这样使用：

$ pwd  # 仅用于说明运行位置
/c/src
$ compile base/time/time.cc base/time/time_unittest.cc
...
[0/47] 5.56s S CXX obj/base/base/time.obj
...
[2/3] 9.27s S CXX obj/base/base_unittests/time_unittest.obj
...

运行 Chromium

构建完成后，你可以直接运行浏览器：

$ out\Default\chrome.exe

（命令中的 “.exe” 后缀其实是可选的）

运行测试目标

测试根据类型和所在目录被划分为多个测试目标。要查看某个单元测试或浏览器测试文件对应的目标，可以使用以下命令：

$ gn refs out\Default --testonly=true --type=executable --all chrome\browser\ui\browser_list_unittest.cc
//chrome/test:unit_tests

在上述示例中，目标是 unit_tests。可以通过以下命令构建该二进制文件：

$ autoninja -C out\Default unit_tests

你可以直接运行该测试二进制文件来执行测试。也可以使用 --gtest_filter 参数来限制运行的测试，例如：

$ out\Default\unit_tests.exe --gtest_filter="BrowserListUnitTest.*"

你可以在 GitHub 页面 了解更多 GoogleTest 的信息。

构建安装包

构建 mini_installer 目标可以生成一个自包含的安装器。该安装器包含在一台机器上安装浏览器所需的全部内容：

$ autoninja -C out\Default mini_installer

更多信息请参考：

• //chrome/installer/setup/README.md
• //chrome/installer/mini_installer/README.md

更新源码

要更新现有源码目录，可以运行：

$ git rebase-update
$ gclient sync -D

第一条命令会更新 Chromium 主源码仓库，并将你的本地分支 rebase 到主分支的最新代码（即 Git 分支 origin/main）。如果你不想使用该脚本，也可以直接使用 git pull 或其他 Git 命令更新仓库。

第二条命令会同步所有子仓库到合适的版本，删除不再需要的子仓库，并根据需要重新运行 hooks。

在 Visual Studio IDE 中编辑和调试

你可以使用 Visual Studio IDE 来编辑和调试 Chrome，可以选择是否开启 Intellisense 支持。

使用 Visual Studio Intellisense

如果你希望在开发 Chromium 时使用 Visual Studio 的 Intellisense，请在执行 gn gen 生成输出目录时添加 --ide 参数。如下是一个例子，假设你的 Chromium 路径是 C:\src\chromium，输出目录为 out\Default：

$ gn gen --ide=vs --ninja-executable=C:\src\chromium\src\third_party\ninja\ninja.exe out\Default
$ devenv out\Default\all.sln

这将生成一个 all.sln 解决方案文件，可在 Visual Studio 中打开。虽然实际编译仍由 Ninja 完成，但你仍然可以使用 IDE 的大部分功能（Chromium 不支持 Visual Studio 的原生编译方式）。

注意事项：

• 如果你再次手动执行 gn gen，需要重新传递 --ide 参数；
• 通常 GN 会在构建过程中自动保持解决方案文件更新；
• 生成的解决方案包含数千个项目，加载会非常缓慢。

为了优化加载速度，可使用 --filters 限制只生成你关心的代码目录的项目文件。例如，只关心 chrome 目录：

$ gn gen --ide=vs --ninja-executable=C:\src\chromium\src\third_party\ninja\ninja.exe --filters=//chrome --no-deps out\Default

你还可以添加多个目录过滤器，例如：

--filters=//chrome;//third_party/WebKit/*;//gpu/*

使用 gn help gen 可查看更多相关选项。

---

不使用 Intellisense 使用 Visual Studio

你也可以不生成 .sln 文件，直接用 Visual Studio 进行调试。例如：

$ devenv /debugexe out\Debug\chrome.exe <你的参数>

这样做的好处是避免了庞大的解决方案加载开销。不过代码导航等功能将无法使用。

可通过安装 VsChromium 插件 弥补这一限制。它提供：

• 代码浏览器；
• 全局代码搜索；
• 快速跳转等功能。

你可以通过 文件 -> 添加 -> 现有项目 添加多个二进制（例如 unit_tests.exe、browser_tests.exe）到解决方案中，然后右键设置为启动项目。

若需设置命令行参数或调试属性，可在 解决方案资源管理器 中右键点击项目 -> 属性 进行配置。

调试所有子进程

默认情况下，Visual Studio 仅调试主浏览器进程。要调试所有子进程，请安装：

• Child Process Debugging Power Tool

同时确保 以管理员身份 启动 Visual Studio，否则会无法附加部分子进程，且不会提示错误。

提升 git 命令性能

启用 untracked cache（缓存未跟踪文件）

运行以下命令进行测试：

$ git update-index --test-untracked-cache

如果输出结果最后是 OK，可开启缓存提升性能：

$ git config core.untrackedCache true

启用 fsmonitor（文件系统监控器）

fsmonitor 可极大加快大仓库（如 Chromium 和 V8）中 git status 等命令速度：

$ git config core.fsmonitor true

反检测指纹浏览器系列教程源码存放地址：https://github.com/itbrowser-net/undetectable-fingerprint-browser
原文地址：https://github.com/chromium/chromium/blob/main/docs/windows_build_instructions.md