在 Windows 上搭建 Chromium 148 内核编译环境：一份实战笔记

本文记录基于 Chromium 148 分支在 Windows 上配置本地工具链的完整过程，涵盖 Visual Studio 2026、Windows SDK 26100、环境变量、常见构建错误，以及「头文件到底从哪来」这类容易被误解的问题。文中不涉及任何具体产品或公司内部命名。

一、背景与目标

Chromium 148 对 Windows 构建环境的要求比旧版本更严格：

Visual Studio 2026 （文档要求 ≥ 17.0，安装目录版本号通常为 18）
Windows 11 SDK 10.0.26100.7705 或更高
Debugging Tools for Windows（≥ 10.0.26100.3323，用于大页 PDB）
编译器实际使用 Chromium 自带的 clang-cl，但头文件、链接器、MFC/ATL 仍依赖本机 VS/SDK

本文目标：本机最小安装 + 本地工具链 （DEPOT_TOOLS_WIN_TOOLCHAIN=0），不依赖 depot_tools 在线下载 VS 工具链包。

二、Visual Studio：装什么、不装什么

2.1 推荐方案

安装 Visual Studio Community 2026，在初始界面选择：

「手动选择工作负载和组件」（不要从 VS 2022 复制配置，否则会带入旧 SDK 和多余组件）。

2.2 工作负载（只勾 1 个）

勾选	名称
✅	使用 C++ 的桌面开发

不要勾 .NET、Python、Web、UWP、游戏、Azure 等无关工作负载。

2.3 安装详细信息

在该工作负载下确认：

组件	说明
MSVC ... x64/x86 ...（最新 / Latest）	即 VC145 工具集，界面可能不写「v145」
Windows 11 SDK (10.0.26100.x)	版本 ≥ 26100.7705
C++ MFC (x86 & x64)	文档明确要求
C++ ATL (x86 & x64)	文档明确要求；扩展模块若用 WTL/ATL 也依赖此项

只编 x64 时，不必安装 ARM64 相关组件。

2.4 关于「MSVC v145 找不到」

VS 2026 安装器里往往不会出现「v145」字样，应搜索：

x64 / x86 → MSVC Build Tools for x64/x86 (Latest)
14.51 → 对应 v145 工具集版本号
生成工具 → C++ x64/x86 生成工具

装完后可在 cmd 中验证：

bat 复制代码

"%ProgramFiles%\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
dir "%VCToolsInstallDir%"

若存在 14.5x.xxxxx 目录，即 v145 工具集已就绪。

2.5 能否不装 VS 2026？

方案	是否可行
不装 VS，只用 depot_tools 默认工具链	✅ 可以，但会在线下载一套 VS 2026 + SDK（体积大）
只装 VS 2022，不装 2026	⚠️ 代码里 2022 仍在兼容列表，但官方不保证；易编译/链接失败，运行库为 VC143 而非 VC145
只装 Windows SDK，完全不装 VS	❌ 不行（详见 [3.4 节](#方案是否可行不装 VS，只用 depot_tools 默认工具链 ✅ 可以，但会在线下载一套 VS 2026 + SDK（体积大）只装 VS 2022，不装 2026 ⚠️ 代码里 2022 仍在兼容列表，但官方不保证；易编译/链接失败，运行库为 VC143 而非 VC145 只装 Windows SDK，完全不装 VS ❌ 不行（详见 3.4 节）)）

结论：要么本机装 VS 2026，要么让 depot_tools 下载工具链；无法「零 VS」编译。

三、Windows SDK 26100：独立安装 vs VS 附带

3.1 两条路径（二选一即可）

路径 A（推荐） ：在 VS Installer 的「单个组件」里勾选 Windows 11 SDK (10.0.26100.x)，与 VS 同一次装完。

路径 B ：单独运行 Windows SDK 安装程序，不需要先装好 VS。

3.2 最小勾选（单独装 SDK 时）

勾选	说明
✅ Debugging Tools for Windows	大 PDB 必需
✅ Windows SDK for Desktop C++ x86 Apps	工具链需要
✅ Windows SDK for Desktop C++ amd64 Apps	主目标 x64
❌ WPT、App Verifier、.NET SDK、UWP、认证工具等	编内核用不到

只编 x64 时，arm64 组件可取消。

3.3 装完后务必确认 Debugging Tools

控制面板 → 程序和功能 → Windows Software Development Kit 10.0.26100.x → 更改

确认 Debugging Tools for Windows 已勾选（VS 里勾了 SDK 后若仍缺，可在此补装）。

3.4 只装 SDK 26100、不装 VS 2026 会怎样？

很多人看到 [3.1 路径 B](#3.1 路径 B) 写着「单独装 SDK 不需要先装好 VS 」，会误以为只装 SDK 就能编 Chromium。实际上 SDK 只覆盖构建依赖的一部分，链接器和 VS 专有组件仍必须有。

3.4.1 直接后果：构建会在工具链检测阶段失败

Chromium 148 要求 VS 2026 + SDK 26100 ，两者缺一不可。源码 build/vs_toolchain.py 会按 2026 → 2022 → 2019 顺序检测本机 VS；若设置了 DEPOT_TOOLS_WIN_TOOLCHAIN=0 却找不到任何受支持的 VS，gn gen / gclient 阶段就会直接报错：

text 复制代码

No supported Visual Studio can be found.
Supported versions are: 2026 (18.0), 2022 (17.0), ...

此时连 ninja 编译都到不了。

3.4.2 SDK 26100 能做什么、不能做什么

组件	SDK 26100	VS 2026
`<windows.h>`、Windows API	✅	---
UCRT（`<stdio.h>` 等）	✅	---
`link.exe` 链接器	❌	✅
MSVC 配套头文件 / `.lib`	❌	✅
ATL / MFC（`<atlbase.h>` 等）	❌	✅
VC145 运行库（`Microsoft.VC145.CRT`）	❌	✅
编译器	---	Chromium 自带 clang-cl

官方 windows_build_instructions.md 写得很明确：

The clang-cl compiler is used but Visual Studio's header files, libraries, and some tools are required.

也就是说：编译器是 Chromium 自带的，但头文件、库、链接器仍依赖 VS。

3.4.3 只装 SDK 时还会遇到的坑（即便机器上有旧版 VS）

若只装 SDK 26100、用 VS 2022 顶着编，还可能踩到这些坑：

问题	说明
SDK 版本检查	代码要求 `NTDDI_WIN11_GE`，即 26100 SDK 必须有；光有 VS 2022 不够
工具链不匹配	会退回 VC143 ，官方 CI 用 VC145；可能出现编译/链接错误，或运行库不一致
SDK 最小安装缺文件	例如 `dxil.dll` 在 `bin\10.0.26100.0\x64\` 缺失，Dawn 构建报错（见 [第四节](#问题说明 SDK 版本检查代码要求 NTDDI_WIN11_GE，即 26100 SDK 必须有；光有 VS 2022 不够工具链不匹配会退回 VC143，官方 CI 用 VC145；可能出现编译/链接错误，或运行库不一致 SDK 最小安装缺文件例如 dxil.dll 在 bin\10.0.26100.0\x64\ 缺失，Dawn 构建报错（见第四节） Debugging Tools 未装大页 PDB（>4 GiB）需要 Debugging Tools ≥ 10.0.26100.3323 Win10 旧系统 26100 SDK 的 d3dcompiler_47.dll 在 Win10 1909 及更早可能触发 UCRT 相关错误（见 9.1 节）)）
Debugging Tools 未装	大页 PDB（>4 GiB）需要 Debugging Tools ≥ 10.0.26100.3323
Win10 旧系统	26100 SDK 的 `d3dcompiler_47.dll` 在 Win10 1909 及更早可能触发 UCRT 相关错误（见 [9.1 节](#问题说明 SDK 版本检查代码要求 NTDDI_WIN11_GE，即 26100 SDK 必须有；光有 VS 2022 不够工具链不匹配会退回 VC143，官方 CI 用 VC145；可能出现编译/链接错误，或运行库不一致 SDK 最小安装缺文件例如 dxil.dll 在 bin\10.0.26100.0\x64\ 缺失，Dawn 构建报错（见第四节） Debugging Tools 未装大页 PDB（>4 GiB）需要 Debugging Tools ≥ 10.0.26100.3323 Win10 旧系统 26100 SDK 的 d3dcompiler_47.dll 在 Win10 1909 及更早可能触发 UCRT 相关错误（见 9.1 节）)）

3.4.4 可行替代方案

方案	说明
VS 2026 + SDK 26100（推荐）	官方路径，最省心
不装本机 VS，用 depot_tools 在线工具链	设 `DEPOT_TOOLS_WIN_TOOLCHAIN=1`（默认），`gclient` 会下载一套 VS 2026 + SDK；体积大，需网络
只装 SDK + VS 2022	可能暂时能编，官方不保证；长期风险高（见 [第六节](#方案说明 VS 2026 + SDK 26100（推荐）官方路径，最省心不装本机 VS，用 depot_tools 在线工具链设 DEPOT_TOOLS_WIN_TOOLCHAIN=1（默认），gclient 会下载一套 VS 2026 + SDK；体积大，需网络只装 SDK + VS 2022 可能暂时能编，官方不保证；长期风险高（见第六节）只装 SDK，零 VS ❌ 不可行)）
只装 SDK，零 VS	❌ 不可行

3.4.5 一句话结论

SDK 26100 解决的是「Windows API / UCRT」；VS 2026 解决的是「链接器、MSVC 库、ATL/MFC、运行库配套」。

只装 SDK 不装 VS 时：

设 DEPOT_TOOLS_WIN_TOOLCHAIN=0（本机工具链）→ 直接失败
不设（用 depot_tools 下载）→ 可以编，但等于让 depot_tools 替你装 VS 2026，并不是「零 VS」

若目标是本机最小安装，应装 VS 2026 Build Tools +「使用 C++ 的桌面开发」+ MFC/ATL ；SDK 可在 VS Installer 里一并勾选，或按 [3.1 路径 B](#3.1 路径 B) 单独装 26100 SDK 作为补充。

四、经典坑：`dxil.dll` 缺失

4.1 报错现象

text 复制代码

ninja: error: 'C:/Program Files (x86)/Windows Kits/10/bin/10.0.26100.0/x64/dxil.dll',
needed by 'dxil.dll', missing and no known rule to make it

4.2 原因

Dawn 构建会从 SDK 的 bin 目录复制 dxil.dll（DXIL 着色器签名库）。最小化 SDK 安装后，常见情况是：

目录	`dxcompiler.dll`	`dxil.dll`
`bin\10.0.26100.0\x64\`	✅	❌ 缺失
`bin\10.0.26100.0\x86\`	✅	✅
`Redist\D3D\x64\`	---	✅

Everything 搜索只列出含 dxil.dll 的路径 ，所以 26100 下可能只看到 x86/arm64，不是 x64 目录不存在 ，而是 x64 里没装这个文件。

4.3 修复（管理员 cmd）

bat 复制代码

copy /Y "C:\Program Files (x86)\Windows Kits\10\Redist\D3D\x64\dxil.dll" ^
         "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\"

copy /Y "C:\Program Files (x86)\Windows Kits\10\Redist\D3D\x86\dxil.dll" ^
         "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"

验证后直接重新 ninja，无需 gn gen。

五、环境变量配置

本机工具链需设置以下变量（改完后新开 cmd）：

变量名	值	说明
`Path`（最前）	`...\depot_tools`	必须在 Python/Git 之前
`DEPOT_TOOLS_WIN_TOOLCHAIN`	`0`	使用本机 VS，不下载在线工具链
`vs2026_install`	`C:\Program Files\Microsoft Visual Studio\18\Community`	以本机实际路径为准

注意：VS 2026 安装路径常为 ...\18\Community，而非 ...\2026\Community。

旧的 `vs2022_install` 要删吗？

不删也能编------工具链按 2026 → 2022 → 2019 顺序检测，有 2026 就用 2026。

建议删除或留空 ，避免 vs2026_install 配错时静默退回 VS 2022，导致 VC143/VC145 不一致。

验证命令

bat 复制代码

echo %DEPOT_TOOLS_WIN_TOOLCHAIN%
echo %vs2026_install%
where gclient
where python3
"%vs2026_install%\VC\Auxiliary\Build\vcvarsall.bat" amd64
where link

六、为什么要 VS 2026？只用 VS 2022 会怎样？

6.1 代码层面的「硬要求」

SDK 有一条编译期检查（与 VS 年份无关）：

cpp 复制代码

#if !defined(NTDDI_WIN11_GE)
#error Windows 10.0.26100.0 SDK or higher required.
#endif

即 SDK 26100 必须有；它可以装在 VS 2022 旁边。

VS 版本在 build/vs_toolchain.py 中按优先级检测：2026 → 2022 → ...，只装 2022 时会退回 VC143。

6.2 只用 VS 2022 的风险

方面	VS 2022 (VC143)	VS 2026 (VC145)
官方 CI / 打包工具链	❌ 不测试	✅ 标准环境
C++ 配套头文件 / 链接器	较旧	较新
运行库拷贝	`Microsoft.VC143.CRT`	`Microsoft.VC145.CRT`
长期维护	过渡期可能还能编	官方唯一承诺路径

可能出现：编译错误（新代码 + 旧头文件）、链接错误（新链接选项）、运行库行为差异。下一批代码可能直接编不过。

6.3 为何「强制」升级

这是 Chromium 定期升级 Windows 工具链 的惯例：官方构建、CI、开发者环境对齐；跟进 Win11 24H2+ API；C++/安全修复；减少多套工具链维护成本。文档写必须 VS 2026 = 官方只测试这一条路径。

七、头文件从哪来？（Chromium 特例）

这是很多开发者容易混淆的点。

7.1 通用 Windows C++ 认知

类型	典型来源
C++ 标准库 `<vector>` 等	编译器工具链（MSVC STL / libstdc++ / libc++）
C 库 `<stdio.h>` 等	Windows SDK UCRT
Windows API `<windows.h>`	Windows SDK
ATL/MFC `<atlbase.h>`	Visual Studio 组件

7.2 Chromium 148 的实际分工

头文件	实际来源
`<vector>`, `<string>` 等 C++ 标准库	Chromium 自带 libc++ （`use_custom_libcxx = true`）
`<stdio.h>` 等	Windows SDK (UCRT)
`<windows.h>` 等	Windows SDK
`<atlbase.h>` 等	Visual Studio (ATL/MFC)
谁编译 `.cc`	Chromium 自带 clang-cl
谁链接	VS 的 link.exe + 各类 .lib

编译日志中的 -imsvc .../VC/Tools/MSVC/14.51.../include 仍会存在，因为：

UCRT / Windows API 头文件依赖 SDK + VS 环境；
libc++ 在 Windows 上仍依赖部分 MSVC 头文件；
链接需要 msvcprt.lib / libcpmt.lib 等。

因此：升级 VS 2026 影响的不仅是「标准库路径」，而是整套配套环境------这也是工具链必须跟着升的原因。

7.3 一句话记忆

C++ 标准库：Chromium 自带 libc++

C 运行时 + Windows API：Windows SDK

ATL/MFC：Visual Studio

编译器：Chromium clang-cl；链接器：VS

八、最小安装清单（Checklist）

复制代码

□ VS 2026 Community / Build Tools
  □ 工作负载：使用 C++ 的桌面开发
  □ MSVC x64/x86（Latest / v145）
  □ Windows 11 SDK 10.0.26100
  □ C++ MFC + ATL (x86 & x64)

□ Windows SDK（若 VS 未附带则单独装）
  □ Desktop C++ x86 / amd64
  □ Debugging Tools for Windows

□ 修复 dxil.dll（若 ninja 报错）
  □ 从 Redist\D3D 复制到 bin\10.0.26100.0\x64\

□ 环境变量
  □ DEPOT_TOOLS_WIN_TOOLCHAIN=0
  □ vs2026_install=...\18\Community
  □ Path 最前：depot_tools

□ 磁盘
  □ 源码 + out 目录 ≥ 100GB（NTFS）

□ 验证
  □ gn gen out\Debug
  □ ninja -C out\Debug chrome

九、操作系统支持范围（Win11 / Win10 / Win8？）

这里要区分两种「支持」：在哪台机器上编译 ，和 编出来的浏览器在哪台机器上运行。

9.1 编译环境（开发机 / 构建机）

系统	能否用来编 Chromium 148
Windows 11	✅ 可以（推荐；VS 2026 体验最好）
Windows 10	✅ 可以（官方文档要求 Windows 10 or newer ；VS 2026 需 1909 / 21H2+ 等较新版本）
Windows Server 2016/2019/2022	✅ 一般可以（命令行构建常见）
Windows 8.1 / 8	❌ 不行（无法安装 VS 2026，也不满足构建要求）
Windows 7 及更早	❌ 不行

Chromium 官方 windows_build_instructions.md 写的是 Windows 10 or newer ，因此 Win10、Win11 都能当编译机 ；Win8 及以下不能。

Win10 编译机额外注意

文档对 Win10 1909 及更早 有警告：使用 26100 SDK 时，Dawn 等组件可能因 d3dcompiler_47.dll 动态链接 UCRT 而在旧系统上出问题。建议：

编译机尽量使用 Win10 20H1+ ，或直接使用 Win11；
若遇相关错误，可更新系统 UCRT，或按官方文档用旧 SDK 的 d3dcompiler_47.dll 变通。

9.2 运行环境（用户电脑跑编出的 Chrome）

系统	能否运行 Chromium 148
Windows 11	✅ 支持
Windows 10	✅ 最低要求即为 Win10
Windows 8.1 / 8 / 7	❌ 不支持

源码中安装器有明确判断（chrome/installer/util/install_util.cc）：

cpp 复制代码

// We do not support anything prior to Windows 10.
return base::win::GetVersion() >= base::win::Version::WIN10;

构建配置同样写明 Chromium only supports Windows 10+ （WINVER=0x0A00）。官方 Chrome 早已停止 Win7/8.1 更新，148 这一代只面向 Win10+。

9.3 「Windows 11 SDK」≠ 只能在 Win11 上跑

安装 Windows 11 SDK 26100 指的是开发用头文件/库的版本 ，不是要求用户系统必须是 Win11。

SDK 名称：开发工具版本
运行要求 ：仍是 Windows 10 及以上

Win10 用户完全可以运行用 26100 SDK 编出来的 Chrome。

9.4 速查表

场景	Win11	Win10	Win8/8.1	Win7
安装 VS 2026 并编译	✅	✅（建议较新版本）	❌	❌
运行编出的 Chrome	✅	✅	❌	❌

十、结语

Chromium 148 在 Windows 上的构建环境，表面上是「装 VS + 装 SDK」，实际上是一套精密分工：

clang-cl 负责编译；
libc++ 负责 C++ 标准库；
SDK 26100 负责 Windows API 与 UCRT；
VS 2026 负责链接器、运行库、MFC/ATL 及 libc++ 的 Windows 配套依赖。

最小安装可以省磁盘，但要接受 SDK 组件不全时的手动修补 （如 dxil.dll）。按官方文档装全 VS 2026 + SDK 26100，并正确设置环境变量，是长期最省心的路径。

本文基于 Chromium 148 分支 docs/windows_build_instructions.md 及 build/vs_toolchain.py 等源码整理，环境细节随版本更新可能变化，请以官方文档为准。

在 Windows 上搭建 Chromium 148 内核编译环境：一份实战笔记

一、背景与目标

二、Visual Studio：装什么、不装什么

2.1 推荐方案

2.2 工作负载（只勾 1 个）

2.3 安装详细信息

2.4 关于「MSVC v145 找不到」

2.5 能否不装 VS 2026？

三、Windows SDK 26100：独立安装 vs VS 附带

3.1 两条路径（二选一即可）

3.2 最小勾选（单独装 SDK 时）

3.3 装完后务必确认 Debugging Tools

3.4 只装 SDK 26100、不装 VS 2026 会怎样？

3.4.1 直接后果：构建会在工具链检测阶段失败

3.4.2 SDK 26100 能做什么、不能做什么

3.4.3 只装 SDK 时还会遇到的坑（即便机器上有旧版 VS）

3.4.4 可行替代方案

3.4.5 一句话结论

四、经典坑：dxil.dll 缺失

4.1 报错现象

4.2 原因

4.3 修复（管理员 cmd）

五、环境变量配置

旧的 vs2022_install 要删吗？

验证命令

六、为什么要 VS 2026？只用 VS 2022 会怎样？

6.1 代码层面的「硬要求」

6.2 只用 VS 2022 的风险

6.3 为何「强制」升级

七、头文件从哪来？（Chromium 特例）

7.1 通用 Windows C++ 认知

7.2 Chromium 148 的实际分工

7.3 一句话记忆

八、最小安装清单（Checklist）

九、操作系统支持范围（Win11 / Win10 / Win8？）

9.1 编译环境（开发机 / 构建机）

Win10 编译机额外注意

9.2 运行环境（用户电脑跑编出的 Chrome）

9.3 「Windows 11 SDK」≠ 只能在 Win11 上跑

9.4 速查表

十、结语

四、经典坑：`dxil.dll` 缺失

旧的 `vs2022_install` 要删吗？