1. CEF 编译这件事:为什么代码开发工具比 IDE 更关键
第一次把 CEF 源码拉下来准备编译 chromium 时,多数人会把 Visual Studio 当成主角,真正决定成败的却是一整套代码开发工具:depot_tools 负责拉取与同步,GN 生成构建描述,Ninja 负责实际编译。CEF 是 Chromium 的嵌入式封装,编译产物要能被上层应用以库的形式引用,所以配置一旦写错,后面几小时的等待就白费。这篇面向已经拿到源码、准备在 Windows 上生成工程并跑通编译的读者,把 create.bat、GN_DEFINES、工具链报错和增量编译讲清楚,适合刚接手 CEF 构建、被工具链报错卡住过的同学。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链准备:depot_tools、GN 与 Ninja 各自管什么
2.1 三个工具的分工与调用顺序
CEF 的编译链条比普通 C++ 工程长,原因是它并不是一个独立项目,而是 Chromium 的一个嵌入层。源码同步、构建描述生成、实际编译分别由不同工具负责,弄清谁调用谁,后面看到报错才知道该查哪一层。常见分工如下:
| 工具 | 角色 | 在本流程中的典型动作 |
|---|---|---|
| depot_tools | 源码与工具链管理 | 提供 gclient、gn、ninja 的入口,处理工具链下载与版本标记 |
| GN | 构建描述生成器 | 读取 BUILD.gn,生成 build.ninja 与 VS 工程文件 |
| Ninja | 实际构建执行器 | 读取 build.ninja,按依赖图编译目标文件并链接 |
| Visual Studio | IDE 与本地编译环境 | 提供 MSVC 编译器,承载生成的 cef.sln 工程 |
调用顺序是:先由 depot_tools 把源码和工具链准备好,再由 GN 根据 GN_DEFINES 等参数生成构建文件,最后由 Ninja 执行编译。很多人跳过第二步直接打开 sln 编译,结果发现 GN 参数没生效,产物行为和预期不一致。把这条链路记住,排查时就能判断是“源码没同步好”“GN 参数没传进去”还是“Ninja 编译到一半失败”。
需要强调的是,GN 和 Ninja 都由 depot_tools 携带,不要用系统里另装的版本去替换。版本错配是后面工具链报错的常见来源之一。
2.2 目录约定与源码落位
CEF 的构建脚本对目录结构有隐含假设。材料里出现的路径是 c:\code\chromium_git\chromium\src\cef\create.bat,也就是说 create.bat 必须放在 src\cef 目录下,而不是随便找个地方。GN 在生成工程时会以 src 为根去解析相对路径,脚本放错位置,轻则找不到 BUILD.gn,重则生成一半就中断。
先确认目录结构,再动手改脚本。可以在命令行里逐层检查:
bat复制:: 确认源码根目录存在
cd /d c:\code\chromium_git\chromium\src
:: 确认 cef 目录与 create.bat 都在
dir cef\create.bat
:: 确认 out 目录是否已有历史产物,避免新旧配置混用
dir out
第一行的 cd /d 用于跨盘符切换,Windows 下如果源码不在 C 盘,不加 /d 会切换失败。第二行只检查 create.bat 是否存在,路径必须与后面 GN 使用的根目录一致。第三行查看 out 目录,如果里面有旧的 Release_GN_x86 之类目录,建议先确认它是不是用当前参数生成的,避免增量编译把旧配置带进来。
out 目录是 GN 生成构建文件的默认落点,命名一般带配置后缀,材料里出现的 out\Release_GN_x86 就是一个典型例子。这个目录名不是固定的,但一旦生成,里面会包含 build.ninja、args.gn 以及 VS 工程文件。排查问题时,先看这个目录里有没有 args.gn,能快速判断 GN 是否真正执行过。
提示:源码根目录、cef 目录、out 目录三者的相对关系不要随意调整,构建脚本里大量路径是按这个结构写死的。
2.3 环境自检:VS 版本、Python、PATH
工具链准备好之后,先做一轮自检,比编译到一半再回头查要省时间。材料里的 GN 参数用了 --ide=vs2019,说明生成工程时指定了 Visual Studio 2019 的工程格式;如果本机装的版本对不上,生成阶段就可能报错。自检要覆盖三件事:VS 是否可用、depot_tools 是否在 PATH 里、Python 是否由 depot_tools 自带。
bat复制:: 查看 depot_tools 是否在 PATH 中
where gclient
where gn
where ninja
:: 查看 VS 安装路径是否被工具链识别
echo %VSINSTALLDIR%
:: 确认 Python 来源,优先使用 depot_tools 自带的解释器
where python
where 会按 PATH 顺序列出所有匹配项,如果 gn 或 ninja 指向了非 depot_tools 目录,就存在版本冲突风险。VSINSTALLDIR 为空不代表 VS 没装,只说明当前命令行不是从开发者命令提示符启动的,编译阶段工具链会自己去探测。Python 这一项最容易被忽略:depot_tools 自带一份 Python,路径类似 bootstrap-2@3_8_10_chromium_23_bin\python\bin\python.exe,如果系统 Python 抢先被调用,脚本行为可能不一致。
自检完成后,再执行一次工具链同步。材料里的报错信息明确给出了这条命令:
bat复制:: 同步工具链与依赖,报错时优先尝试
gclient runhooks
gclient runhooks 会按当前配置重新执行钩子,补齐工具链和第三方依赖。它适合在“源码在、但工具链版本标记对不上”的情况下先跑一遍。要注意,它并不是万能的,后面会看到有些环境下跑完仍然失败,那时就要换思路,而不是反复执行同一条命令。
3. create.bat 与 GN 参数:把编译配置写进脚本
3.1 create.bat 的原始模板与逐行含义
create.bat 是整套构建的入口脚本,它把 GN 需要的环境变量设好,再调用 cef_create_projects.bat 真正生成工程。材料给出的原始模板是:
bat复制set GN_DEFINES=is_component_build=true
# Use vs2017 or vs2019 as appropriate.
set GN_ARGUMENTS=--ide=vs2019 --sln=cef --filters=//cef/*
call cef_create_projects.bat
这三行看着简单,含义要拆开看。GN_DEFINES 是传给 GN 的构建参数,is_component_build=true 表示按组件方式构建,产物会拆成多个动态库,而不是尽量合并成少量大库。GN_ARGUMENTS 控制生成什么形态的工程:--ide=vs2019 指定生成 VS2019 工程,--sln=cef 指定解决方案文件名,--filters=//cef/* 把工程过滤到 cef 目录相关目标,避免把整个 Chromium 的目标都塞进解决方案。最后一行 call cef_create_projects.bat 才是实际执行生成的动作。
这里有个容易踩的点:# 开头那行是注释,在 bat 里并不是合法注释语法,实际执行时可能被当成命令。写脚本时要么删掉,要么改成 :: 或 rem。材料里保留它更像是给人看的说明,直接照抄进 bat 会有隐患。
脚本必须放在 src\cef 目录下,因为 cef_create_projects.bat 用相对路径定位源码根。放错位置时,脚本可能直接提示找不到文件,或者在生成阶段报路径错误。
3.2 按需改 GN_DEFINES:编码器与组件构建
原始模板只是最小可用配置。材料里给出的修改版更接近实际项目需要:
bat复制@echo off
set CEF_USE_GN=1
set GN_DEFINES=proprietary_codecs=true ffmpeg_branding=Chrome
set GN_ARGUMENTS=--ide=vs2019 --sln=cef --filters=//cef/*
call cef_create_projects.bat
CEF_USE_GN=1 表示走 GN 构建体系,这是 CEF 新版本的标准路径。GN_DEFINES 换成了两个参数:proprietary_codecs=true 打开专有编解码支持,ffmpeg_branding=Chrome 指定 FFmpeg 的品牌配置,两者共同决定音视频编码能力。如果上层应用要播放或处理特定格式的媒体,这两个参数漏掉,编译能过,但运行时功能会缺一块,属于典型的“编译成功、功能不对”。
组件构建参数 is_component_build=true 被去掉了,这意味着默认按静态方式构建。组件构建的好处是链接快、增量编译快,代价是运行时要把多个 DLL 一起分发,少一个就起不来;静态构建产物更集中,但链接阶段更慢。选哪种取决于交付方式:本机调试选组件构建省时间,对外发包选静态构建省心。
| 参数 | 作用 | 适用场景 | 代价 |
|---|---|---|---|
| is_component_build=true | 拆成多个动态库 | 本机开发、频繁增量编译 | 分发需带齐 DLL |
| proprietary_codecs=true | 打开专有编解码 | 需要完整媒体能力 | 构建配置更复杂 |
| ffmpeg_branding=Chrome | 指定 FFmpeg 品牌 | 与编解码参数配套 | 参数不匹配时行为异常 |
改完脚本后不要急着编译,先确认参数真的传进了 GN。生成完成后,out 目录下的 args.gn 会记录本次生效的参数,打开看一眼比凭记忆靠谱。
3.3 生成 VS 工程与 out 目录结构
执行 create.bat 后,GN 会在 out 目录下生成构建文件和 VS 工程。成功时命令行不会有太多输出,失败时通常会停在 Regenerating ninja files 或 FAILED: build.ninja 这类字样上。生成完成后,目录里大致会有这些内容:
| 文件/目录 | 用途 |
|---|---|
| build.ninja | Ninja 的构建描述,编译的实际依据 |
| args.gn | 本次 GN 参数的落盘记录 |
| cef.sln | 生成的 VS 解决方案 |
| obj/ | 中间目标文件目录 |
args.gn 值得单独看一眼,它是排查“参数到底生效没有”的第一手证据。cef.sln 则是给习惯 IDE 的人用的入口,打开后可以选配置编译,但底层仍然是 Ninja 在跑。如果 sln 打不开或项目为空,多半是 --filters=//cef/* 过滤后没有匹配到目标,或者生成阶段已经失败,只是没注意到错误输出。
生成阶段成功不代表编译一定成功,它只完成了“构建描述”这一步。真正耗时的是下一步的 Ninja 编译。
4. 用 Ninja 驱动 CEF 编译:代码开发工具的参数与产物
4.1 生成之后怎么发起编译
工程生成后,编译有两条路:打开 cef.sln 用 VS 编译,或者在命令行用 Ninja 编译。两者底层是同一套 build.ninja,差别在交互方式。命令行更适合自动化和排查,因为输出直接、参数可控。常用形式是:
bat复制:: 进入源码根目录
cd /d c:\code\chromium_git\chromium\src
:: 查看当前 out 目录下有哪些可构建目标
ninja -C out\Release_GN_x86 -t targets
:: 构建全部目标,实际目标名以 targets 输出为准
ninja -C out\Release_GN_x86
-C 指定构建目录,Ninja 会到该目录下读取 build.ninja。-t targets 是查询模式,列出所有可构建目标,先看再编,避免拼错目标名导致空跑。第三条不带目标名时默认构建全部,CEF 的目标数量大,第一次全量编译耗时会很长,材料里也提到“得编译好长时间”,这是正常现象,不是卡死。
如果只想先验证工具链是否能跑通,可以先编一个小目标,成功后再全量。判断是否卡死的方法很简单:看输出是否还在滚动,以及 out 目录下的 obj 是否在持续产生新文件。长时间没有任何输出、磁盘也不增长,才需要怀疑异常。
4.2 编译时长与增量编译
CEF 全量编译动辄数小时,时间和机器核数、磁盘、是否组件构建都有关系。想缩短等待,重点不在“换更快的命令”,而在减少重复全量编译。几个实用做法:
第一,保持 out 目录稳定。每次改参数都换一个新目录,旧目录的增量成果就废了;反过来,如果参数确实变了,继续用旧目录又可能因为缓存不一致出现奇怪问题。我的习惯是参数小改时先试增量,出现无法解释的链接错误再换干净目录。
第二,优先组件构建做日常开发。is_component_build=true 下改动一个源文件,重新链接的库更少,迭代明显更快。代价是分发时要带一堆 DLL,这个代价在开发阶段可以接受。
第三,别在编译过程中改源码或改 args.gn。Ninja 的依赖图是生成时确定的,中途改参数不会自动重生成,容易得到一个“看起来编过了、实际配置是旧的”产物。
bat复制:: 增量编译:不清理 out 目录,直接再次执行
ninja -C out\Release_GN_x86
:: 需要彻底重来时的做法:换一个干净的 out 目录名重新生成
:: 不要直接删 build.ninja 后继续用旧目录
第二条注释是血泪经验:手工删构建文件再复用旧目录,容易出现依赖状态不一致,报错信息还很难指向根因。要重来就换目录,让 GN 从头生成,状态最干净。
4.3 产物位置与验证
编译成功后,产物分布在 out 目录及其子目录里。验证不要只看“命令返回 0”,至少确认三件事:目标文件是否生成、依赖的动态库是否齐全、能否被一个最小程序加载。材料没有给出具体的产物文件名,实际名称以 Ninja 的目标输出为准,用 -t targets 能看到目标,构建后在 out 目录下按目标名找对应文件即可。
验证时建议按“先小后大”的顺序:先用一个最小可执行目标确认工具链和运行时没问题,再编完整目标。直接上大目标,一旦失败,错误可能淹在几千行输出里,定位成本高得多。
5. 编译期排查:工具链报错与常见坑
5.1 现象:Toolchain is out of date
现象:执行生成或编译时,输出停在 [0/1] Regenerating ninja files,随后提示 Toolchain is out of date. Run "gclient runhooks" to update the toolchain, or set DEPOT_TOOLS_WIN_TOOLCHAIN=0 to use the locally installed toolchain.,接着是 Python 的 traceback,最后以 FAILED: build.ninja 结束。
原因:工具链的版本标记与本机实际环境对不上。工具链脚本尝试去校验或下载指定版本的工具链,校验不通过就中断。材料里的报错里能看到 get_toolchain_if_necessary.py 带了 --no-download 参数,说明当时是在“不下载、只用本地”的模式下校验失败。
解决:材料给出的有效做法是设置环境变量,让构建改用本地已安装的工具链:
bat复制:: 让构建使用本地工具链,跳过工具链版本校验与下载
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
设置之后重新执行生成,材料里记录的结果是“已经在编译了”。注意这个变量只在当前命令行窗口有效,换窗口要重设。如果希望长期生效,可以写进用户环境变量,但团队协作时更推荐写进构建脚本,避免每个人环境不一致。
5.2 现象:gclient runhooks 跑完仍然失败
现象:按提示执行了 gclient runhooks,命令本身没有明显报错,但再次生成时同样的工具链错误又出现。
原因:runhooks 负责的是钩子和依赖同步,它不保证工具链版本校验一定通过。当本机工具链与期望版本存在结构性差异时,同步动作补不上这个缺口。
解决:不要在同一条命令上反复试。先确认 DEPOT_TOOLS_WIN_TOOLCHAIN 是否设置,再确认 PATH 里的 gn、ninja 是否来自 depot_tools。如果两者都正常仍然失败,检查 out 目录里是否有上一次失败留下的半成品,换一个干净的 out 目录重新生成。材料里的实际路径是 out\Release_GN_x86,换目录时保持命名规则一致,方便后续对照。
5.3 现象:visual_studio_version.gni 报脚本返回非零
现象:错误输出里出现 ERROR at //build/config/win/visual_studio_version.gni:26:7: Script returned non-zero exit code.,并伴随 exec_script("../../vs_toolchain.py", [ "get_toolchain_dir" ], "scope") 和 FAILED: build.ninja。
原因:GN 在生成阶段调用 vs_toolchain.py 去获取工具链目录,这个脚本返回非零,GN 就判定构建描述生成失败。根因仍然指向工具链定位,可能是 VS 版本不匹配、工具链目录缺失,或者上一条的版本校验失败连锁导致。
解决:先解决工具链定位问题,再回头看这个报错。顺序是:设置 DEPOT_TOOLS_WIN_TOOLCHAIN=0,确认 --ide=vs2019 与本机 VS 版本匹配,然后用干净的 out 目录重新生成。不要试图直接改 visual_studio_version.gni 绕过,那会把问题推到更靠后的编译阶段,错误更难读。
5.4 现象:编译通过但媒体功能缺失
现象:工程能编过,最小程序也能加载,但涉及特定音视频格式的功能表现异常或直接不可用。
原因:GN_DEFINES 里没有打开 proprietary_codecs=true 和 ffmpeg_branding=Chrome,构建时按默认配置裁剪了编解码能力。这类问题不会在编译期报错,属于配置层面的“静默缺失”。
解决:按第 3 章的修改版脚本补上这两个参数,换干净 out 目录重新生成并编译。补参数后务必检查 args.gn 是否记录了新值,确认参数真的进了 GN,而不是只改了脚本没生效。
5.5 现象:组件构建产物拷到别的机器起不来
现象:本机编译运行正常,把产物拷到另一台机器后启动失败,提示缺少某个动态库。
原因:使用了 is_component_build=true,产物被拆成多个动态库,只拷了主程序或部分库,依赖不完整。这类问题和代码无关,纯属交付方式没跟上构建方式。
解决:组件构建的产物要么整目录打包分发,要么改用静态构建重新出一版。团队里最好在脚本注释里写清当前用的是哪种构建方式,避免下一个人接手时按另一种方式理解产物。
6. 进阶:把编译参数固化成脚本与自检习惯
走到能稳定编译这一步,下一步是把“这次能编过”变成“谁拿到都能编过”。我的做法是把 create.bat 固定成一份带注释的模板,参数改动只在一个地方发生,并在脚本里显式处理工具链变量:
bat复制@echo off
:: 使用本地工具链,规避版本校验失败
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
:: 打开 GN 构建体系
set CEF_USE_GN=1
:: 编码能力按需打开;组件构建按开发/发布切换
set GN_DEFINES=proprietary_codecs=true ffmpeg_branding=Chrome
:: set GN_DEFINES=is_component_build=true
set GN_ARGUMENTS=--ide=vs2019 --sln=cef --filters=//cef/*
call cef_create_projects.bat
这份脚本把“环境变量、GN 参数、生成入口”三件事收在一处,注释里保留了组件构建的开关,切换时只动注释,不靠记忆。每次改完参数,我的自检顺序固定为:先看 args.gn 确认参数落盘,再看 -t targets 确认目标存在,最后才发起编译。三步都过,基本不会出现编到一半才发现配置错了的情况。
产物验证也建议固化成清单:目标文件是否生成、依赖库是否齐全、最小程序能否加载、涉及媒体的功能是否实际可用。前两项能自动化检查,后两项需要跑一次实际用例,别省。
从那以后我每次接手新的 CEF 编译环境,都强制先跑一遍目录检查、工具链自检和 args.gn 核对,再开始编译;被 Toolchain is out of date 卡过一次之后,就再也不想靠反复 gclient runhooks 碰运气了。希望帮到你。
