简介CEF-win64版本5563是基于Visual Studio 2019编译的Chromium Embedded Framework工程包面向需要在Windows 64位应用中嵌入浏览器内核的C开发者尤其适合在线教育、直播、视频会议等对视频播放要求较高的场景。该版本已开启H264/H265编解码支持可直接用于构建具备高清视频能力的客户端。压缩包共1055个文件、约278.47MB以539个h头文件与359个cc源文件承载核心接口与实现配套58个pak资源包、14个dll动态库及manifest、pem证书与测试用例另有CMakeLists.txt、cef_paths.gypi等构建配置和README说明文档便于通过CMake做二次开发与定制编译。目前已有486人学习下载。读者可获得可编译的CEF工程骨架、完整的头文件引用与构建脚本并借助内置tests示例验证功能省去自行编译Chromium的高成本环节。1. 官方包放不出 H.264win64 版 CEF 的第一道坎前阵子接手一个内嵌浏览器的桌面端项目验收页里有一段 mp4 和一段 H.265 编码的监控回放。程序跑起来文字图片都正常唯独两个 video 元素一片漆黑控制台躺着 MEDIA_ERR_SRC_NOT_SUPPORTED。换上官方发布的 CEF win64 二进制包同样的页面照样不播——这不是渲染层的问题而是官方预编译包默认没开专有编解码器。CEFChromium Embedded Framework是把 Chromium 嵌进桌面程序的框架win64 版本要支持 H264/265靠的不是改几行调用代码而是从源码用 VS2019 工具链重新编一份开了 proprietary_codecs 的产物。官方为了产物能直接分发H.264、AAC 这类带专利的解码器一律不带H.265 更是只在平台解码通道下才可能可用。这篇笔记就拆这条路开关改哪几个、编译怎么走、接进 VS2019 工程后怎么验证、翻车点在哪。2. 编解码开关拆解proprietary_codecs 与 ffmpeg_branding 到底改了什么动手编译之前先把因果链捋清楚。很多人以为只要在 GN 里加一句 proprietary_codecs true 就万事大吉实际编出来的包还是黑屏原因通常是只改了半条链——解码器进没进 libcef.dll 和播放器认不认这个 codec string是两件事。2.1 FFmpeg 的两个分支Chromium 版与 Chrome 版上游的第三方 FFmpeg 仓库有两套编译配置一套叫 Chromium 品牌只包含 VP8/VP9/AV1/Opus/Vorbis 这类无专利负担的编解码器另一套叫 Chrome 品牌额外把 H.264 的解析与解码、AAC 音频、MP3 这些加了进去。ffmpeg_branding 这个 GN 变量就是用来在两者之间切换的填 Chromium 是默认值填 Chrome 才会把 H.264 那部分源码编进去。这里有个容易误判的地方ffmpeg_branding Chrome 只解决 FFmpeg 这一层也就是软件解码和封装格式解析。浏览器里实际走哪条解码路径还取决于硬件能力和媒体管线配置H.264 在 Windows 上优先尝试 D3D11 硬解失败才回落到 FFmpeg 软解H.265 则完全不同它在上游默认走的是平台解码器通道Windows 上是 Media Foundation也就是说系统侧得具备 HEVC 解码能力光把 FFmpeg 品牌改成 Chrome 未必够。所以「CEF 支持 H.264/265」这句话在工程上要拆成两个独立问题H.264 主要靠 proprietary_codecs ffmpeg_branding 解决H.265 靠平台解码开关加系统解码器两者不要混为一谈否则排查时会绕远路。2.2 三个开关的职责边界开关作用层不开的后果常见误用proprietary_codecsGN 全局开关控制是否把专利编解码器纳入构建mp4 页面直接 MEDIA_ERR_SRC_NOT_SUPPORTED只开这个不改 branding产物里仍没有 H.264 实现ffmpeg_branding决定 FFmpeg 用哪套 codec 列表编译有 mp4 容器解析但解不出画面常见「有声无画」开了却因增量构建没重新编 third_party/ffmpegenable_platform_hevc决定是否启用平台侧 HEVC 解码通道H.265 文件黑屏报 DEMUXER_ERROR_COULD_NOT_OPEN以为开了就能软解实际仍依赖系统解码器三个开关的先后关系是proprietary_codecs 是总闸ffmpeg_branding 决定软解能力平台 HEVC 开关决定硬解通道。只开总闸不开品牌等于买了设备没接线只开 HEVC 不开总闸连封装都解析不了。提示GN 参数在不同分支上有增删enable_platform_hevc 和新一些的 enable_hevc_parser_and_hw_decoder 并非每个分支都存在。改之前先跑 gn args --list out/xxx 把可用参数列一遍别照抄别人的 args.gn 直接怼。2.3 十秒钟体检先判断手上的包值不值得折腾如果你手上已经有一个第三方给的 libcef.dll别急着接进工程先粗筛一下。最直接的办法是在 dll 里搜 codec string虽然字符串可能被优化或落在 pak 里但作为第一道筛选够用。# 在 libcef.dll 二进制里粗查 H.264/H.265 的 codec string # 命中说明产物里很可能带了对应解码器没命中也不要立刻下结论 $dll C:\cef_binary\Release\libcef.dll $hits Select-String -Path $dll -Pattern avc1,hev1,hvc1 -Encoding Byte -AllMatches if ($hits) { Write-Host 疑似包含 H.264/H.265 解码器 } else { Write-Host 大概率没开 proprietary_codecs }这段脚本做的是二进制模式匹配Select-String 用 -Encoding Byte 避免把 dll 当文本解码而破坏匹配。avc1 对应 H.264hev1 和 hvc1 对应 H.265 的两种封装标记。需要说明的是它只能证伪不能证实命中不代表一定能播因为解码器注册还受媒体管线配置影响没命中则基本可以判定这个包不用试了直接换。更靠谱的验证方式是编一个最小页面丢进 cefclient 跑用 MediaSource.isTypeSupported 逐条探这个后面第 6 章会给完整代码。我一般两手都做先用字符串粗筛掉明显不合格的包省下几十分钟的接入时间。2.4 为什么锁定 VS2019 而不是更新的工具链Chromium 每个分支对 MSVC 版本有硬性要求版本对不上会在编译早期就报一堆 STL 相关的错比如 std::string_view 找不到、constexpr 求值失败。较老的 CEF 分支对应的就是 VS2019 的 MSVC 工具集装 VS2022 反而可能因为 cl.exe 版本过高被 GN 的版本检查拦下。实操上建议装 VS2019 的生成工具而不是完整 IDE勾选「使用 C 的桌面开发」和 Windows 10 SDKSDK 版本按分支的 build 文档要求选不要图新装最新 SDK——某些分支对 SDK 版本也做了断言。装完之后用 vswhere 确认路径能被 depot_tools 找到。# 确认 VS2019 的安装路径和 MSVC 工具集版本depot_tools 靠这个定位编译环境 C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe ^ -version [16.0,17.0) -products * ^ -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^ -property installationPathvswhere 的 -version 区间 [16.0,17.0) 精确锁定 VS2019-requires 保证这个安装确实带了 C 工具集而不是只装了 IDE 壳子。输出为空说明机器上压根没有可用的 VS2019先补装再谈编译。3. VS2019 编译全流程从 gclient sync 到 libcef.dll 落地这一章是整条链里最耗时的部分。Chromium 源码加编译中间产物磁盘留出 100 GB 以上内存 16 GB 起步编译时长视机器从一小时到四小时不等。流程本身不复杂坑集中在环境变量和增量构建上。3.1 环境准备depot_tools 与环境变量depot_tools 是拉代码和跑构建脚本的工具集合必须加到 PATH 最前面否则系统里其他 Python 或 git 会抢在前面导致行为诡异。加完之后设三个环境变量DEPOT_TOOLS_WIN_TOOLCHAIN0 让它用本机 VS2019 而不是自动下载工具链GYP_MSVS_VERSION2019 指定生成器版本DEPOT_TOOLS_UPDATE1 保持工具自更新。# 把 depot_tools 放到 PATH 最前面避免被系统里其他 python/git 抢走 set PATHC:\depot_tools;%PATH% # 使用本机安装的 VS2019而不是让脚本自动下载一份工具链 set DEPOT_TOOLS_WIN_TOOLCHAIN0 set GYP_MSVS_VERSION2019 # 首次拉代码前初始化后面拉取会快很多 gclient --versionDEPOT_TOOLS_WIN_TOOLCHAIN0 这一句尤其关键设成 1 的话脚本会去下载一份独立的工具链几十 GB 不说还经常因为网络问题卡住。gclient --version 能正常输出版本号说明工具链本身可用可以进下一步。3.2 拉代码用官方脚本还是手动 gclient手动流程是写 .gclient 配置再 gclient sync好处是可控坏处是 CEF 和上游 Chromium 的版本对齐要自己盯很容易出现 CEF 代码和 Chromium 源码版本不匹配导致编译报错。我的做法是优先用 CEF 仓库自带的 automate-git.py它把拉代码、切分支、生成工程串成一条命令。# 建工作目录所有源码和产物都放这里面 mkdir C:\cef_build cd C:\cef_build # 一条命令完成拉 Chromium 拉 CEF 切到指定分支 生成 VS 工程 python automate-git.py --urlCEF 源码仓库地址 ^ --branchCEF 分支号 ^ --download-dirC:\cef_build ^ --build-targetcefclient ^ --x64-build --no-debug-build--branch 填你要用的 CEF 分支号这个号必须和上游 Chromium 分支对齐脚本会自动处理映射关系手填错一个数字就会在 sync 阶段报版本冲突。--build-target 指定只编 cefclient够验证用如果要出完整产物就改成 cef。--x64-build 生成 64 位工程--no-debug-build 跳过 Debug 配置能省将近一半时间和磁盘。如果确实要手动来.gclient 大概是这个样子solutions [ { name: src, url: Chromium 源码镜像地址, deps_file: DEPS, managed: True, custom_deps: {}, custom_vars: { checkout_pgo_profiles: False, checkout_nacl: False, }, }, ] target_os [win]custom_vars 里关掉 PGO profile 和 NaCl 是为了省下载量这两个对编解码毫无影响。managed 为 True 表示由 gclient 接管依赖同步。写完之后 gclient sync 会拉一个很长的依赖列表中途断网就再跑一次gclient 支持断点续传。3.3 生成工程GN_DEFINES 怎么拼这一步决定了最终产物带不带 H.264。CEF 的构建脚本通过 GN_DEFINES 环境变量把自定义 GN 参数透传给 gn gen多个参数用空格分隔写在同一个字符串里。# 关键四件套关闭组件化构建、打开专有编解码器、切 Chrome 版 FFmpeg、启用平台 HEVC set GN_DEFINESis_component_buildfalse proprietary_codecstrue ffmpeg_brandingChrome enable_platform_hevctrue # 生成 VS2019 解决方案和 ninja 构建文件 python cef_create_projects.batis_component_buildfalse 表示静态链接成一个大的 libcef.dll分发给最终用户时文件少、不容易漏拷开发期想加快链接速度可以设成 true但那样产物会拆成一堆 dll部署时容易漏文件我一般直接按 false 出包。ffmpeg_brandingChrome 注意大小写写 chrome 小写会被当成未知值静默回落成 Chromium 分支这是最隐蔽的一个翻车点——构建不报错产物就是没 H.264。脚本跑完会在 out 目录下生成 Release_GN_x64 文件夹里面有 build.ninja 和 args.gn。这时候别急着编先打开 args.gn 确认几行关键配置真的写进去了# 确认 GN 参数真的落到了 args.gn而不是只存在于环境变量里 type out\Release_GN_x64\args.gn | findstr /C:proprietary_codecs /C:ffmpeg_branding /C:enable_platform_hevc如果这里看不到那三行说明 GN_DEFINES 没生效常见原因是 set 之后开了新的命令行窗口或者脚本内部又覆盖了一遍 GN_DEFINES。宁可在这停五分钟也别编了两小时才发现白干。3.4 ninja 构建与产物核对# 直接进构建目录跑 ninja-j 按物理核数给别超过内存能扛的范围 ninja -C out\Release_GN_x64 -j 8 cefclient-j 的取值有个土办法物理核数或者内存 GB 数除以 2取小的那个。Chromium 编译单个链接单元内存占用很凶16 GB 机器开到 12 线程会因为 OOM 触发 ninja 的进程被杀表现是莫名其妙的 LINK : fatal error LNK1102。编到一半挂了不用慌ninja 是增量的重跑会从断点继续。编完之后核对产物清单win64 版跑起来至少需要这些文件同目录文件必需性缺失表现libcef.dll必需进程启动即退出找不到入口chrome_elf.dll必需启动崩溃事件日志里是加载器错误icudtl.dat必需界面文字全变方块snapshot_blob.bin / v8_context_snapshot.bin必需JS 引擎初始化失败白屏resources.pak / chrome_100_percent.pak必需控件样式错乱、内置页面打不开locales/*.pak按需中文界面缺失不影响视频libEGL.dll / libGLESv2.dll / d3dcompiler_47.dll建议软渲染回退视频卡顿掉帧vk_swiftshader.dll / vulkan-1.dll建议无 GPU 环境下 WebGL 与合成器异常核对方式很简单把 cefclient.exe 单独拷到一个空目录跑一次缺什么它会明确报出来。这一步不做后面接进自己工程时的崩溃会难定位得多。4. 接进自己的工程VS2019 下的目录布局、链接与首个 mp4编译产物拿到手真正的落地才刚开始。CEF 的接入难点不在 API而在于运行时的文件布局和进程模型——它默认是多进程架构主进程、渲染进程、GPU 进程、Utility 进程各自独立任何一个找不到依赖文件都会静默退出。4.1 目录布局二进制、资源、locales 三者必须分层推荐的摆法是二进制和资源分开发布时整目录打包MyApp/ MyApp.exe libcef.dll chrome_elf.dll libEGL.dll libGLESv2.dll d3dcompiler_47.dll vk_swiftshader.dll vulkan-1.dll icudtl.dat snapshot_blob.bin v8_context_snapshot.bin resources.pak chrome_100_percent.pak locales/ zh-CN.pak en-US.paklocales 目录名不能改pak 文件也不能重命名CEF 内部是按固定相对路径找的。我第一次接的时候图省事把 pak 全平铺在根目录结果是界面能出来但所有内置控件样式丢失排查了半天才发现是资源路径问题。另外 Debug 和 Release 的 libcef.dll 不能混用混用表现为启动即崩事件日志里是 0xc0000005。4.2 CMake 接入 libcef_dll_wrapperCEF 的 C API 需要经过 libcef_dll_wrapper 这层静态库转换不能直接链 libcef.dll 的导出符号。官方产物里带了这个 wrapper 的源码编出来的 libcef_dll_wrapper.lib 要和你的 exe 用同一套运行库配置。cmake_minimum_required(VERSION 3.16) project(MyApp CXX) # CEF 产物的根目录指向解压出来的 cef_binary 文件夹 set(CEF_ROOT C:/cef_binary_win64 CACHE PATH CEF root) # 官方产物自带 cmake 配置直接 include 进来省得手写路径 list(APPEND CMAKE_MODULE_PATH ${CEF_ROOT}/cmake) find_package(CEF REQUIRED) # wrapper 源码随产物一起提供编进自己的工程最省事 add_subdirectory(${CEF_ROOT}/libcef_dll_wrapper libcef_wrapper) add_executable(MyApp WIN32 main.cpp) target_link_libraries(MyApp PRIVATE libcef_lib # 对应 libcef.dll 的导入库 libcef_dll_wrapper # C 接口封装层 ${CEF_STANDARD_LIBS} ) # 构建后把运行时文件拷到输出目录避免手工复制漏文件 add_custom_command(TARGET MyApp POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_directory ${CEF_ROOT}/Release $TARGET_FILE_DIR:MyApp )find_package(CEF) 会解析出 CEF_STANDARD_LIBS里面是 Windows 上必需的 user32、gdi32、ole32 这些系统库漏了会在链接期报一堆未解析符号。POST_BUILD 那段 copy_directory 是把 Release 目录整体拷到输出目录这样每次构建完都能直接跑不用手动同步 dll。如果不用 CMake 而是纯 VS2019 工程配置等价附加包含目录加 include 和 libcef_dll_wrapper/include附加库目录加 Release 和 wrapper 的构建输出附加依赖项填 libcef.lib 和 libcef_dll_wrapper.lib。C/C 里运行时库必须选 /MD 或 /MT 且和 wrapper 一致否则报 LNK2038 的 RuntimeLibrary 不匹配。4.3 启动参数与第一个 mp4CEF 初始化时这几个参数建议显式给上尤其是多进程相关的#include include/cef_app.h int main(int argc, char* argv[]) { CefMainArgs main_args(GetModuleHandle(nullptr)); // 子进程必须走这个分支否则渲染进程无法启动表现为白屏 int exit_code CefExecuteProcess(main_args, nullptr, nullptr); if (exit_code 0) { return exit_code; } CefSettings settings; // 关掉沙箱方便开发期排错正式发布前务必改回 true settings.no_sandbox true; // 日志级别给 info视频相关错误都会落到日志里 settings.log_severity LOGSEVERITY_INFO; // 指定 locales 目录不写会用默认相对路径 CefString(settings.locales_dir_path).FromString(locales); // 指定资源目录pak 文件从这儿找 CefString(settings.resources_dir_path).FromString(.); CefInitialize(main_args, settings, nullptr, nullptr); // ... 创建窗口和浏览器实例 CefShutdown(); return 0; }CefExecuteProcess 必须在初始化之前调用它是子进程的入口分发点漏掉这一步的表现是主窗口能开但页面白屏因为渲染进程压根没起来。no_sandbox 只在开发期开沙箱在有 GPU 和编解码器交互的场景里会拦截部分文件访问正式版关掉沙箱是安全隐患。日志级别设成 INFO 之后媒体管线的失败原因会明确写在 debug.log 里比如 H.264 没编进去会看到 PipelineStatus 相关报错H.265 缺平台解码器会提示没有可用的 hardware decoder。5. 排查清单H.264 有声无画、H.265 黑屏的五个现场这条链上的坑有个共同特点不报错或者报的错指向完全无关的地方。下面五个是我实际踩过、也帮别人定位过的按「现象 → 原因 → 解决」写清楚。5.1 构建期编完了但产物没变现场一改了 GN_DEFINES 重新编mp4 还是黑屏。现象是 ninja 跑得飞快十几分钟就结束了但 libcef.dll 的时间戳和大小跟之前一模一样。原因是 ffmpeg_branding 属于影响 third_party/ffmpeg 编译单元的全局参数改它之后必须先让 GN 重新生成 build.ninja而单纯重跑 ninja 会复用旧的构建图。解决方式是重新执行一次 cef_create_projects.bat 生成工程然后删掉 out\Release_GN_x64\obj\third_party\ffmpeg 目录再编。我现在的习惯是改任何 GN 参数之后先 type args.gn 确认落盘再动手删对应模块的 obj。现场二ffmpeg_branding 写了小写的 chrome构建成功但没 H.264。这个最阴。GN 解析字符串值时大小写敏感写 chrome 不会报错而是走到一个默认分支效果等同于 Chromium。表现是容器能解析、进度条能拖但解码器返回不支持的编码。解决很简单改成首字母大写的 Chrome然后按现场一的流程重编。为了防这个我一般在 args.gn 里加一行 assert或者构建后在产物里搜 avc1 做二次确认。现场三LNK2038 RuntimeLibrary 不匹配。现象是链接期报 libcef_dll_wrapper.lib 和工程主目标的迭代器调试级别冲突Mismatch detected for _ITERATOR_DEBUG_LEVEL。原因是 wrapper 按 Release 编而自己的工程挂在 Debug 配置下两个 CRT 不一致。解决是让两边配置对齐要么工程切 Release要么给 wrapper 单独生成一个 Debug 配置但注意 Debug 的 libcef.dll 体积巨大且性能差验证编解码能力不需要 Debug。5.2 运行期能开窗但播不出现场四H.264 播放只有声音没有画面。现象是 audio 正常video 元素区域纯黑日志里能看到 video decoder 初始化失败。原因通常是 GPU 进程没起来硬解通道建不起来而软解又因为 FFmpeg 品牌没设对而缺失两条路都断了。定位方法是启动时加 --disable-gpu 参数强制走软解如果这时候画面出来了就说明问题在 GPU 侧去查 d3dcompiler_47.dll 和 libGLESv2.dll 是不是漏拷或者显卡驱动版本过低。反过来如果加了参数还是黑屏那就是编解码器根本没编进去回第 3 章重来。现场五H.265 文件黑屏H.264 却正常。这个最容易被误判成编译问题。H.265 在上游走的是平台解码通道Windows 上依赖系统侧的 HEVC 解码组件系统里没装的话无论怎么改 GN 参数都放不出来。验证方法是拿同一个 H.265 文件用系统自带的播放器打开播不了说明是系统侧缺解码器装对应组件即可播得了但 CEF 里不行再回来看 enable_platform_hevc 有没有真的打开以及 args.gn 里那行是不是被覆盖了。注意排查顺序一定要「先系统后框架、先软解后硬解」。反过来的话你会花大量时间在重编 Chromium 上最后发现是机器少装了一个解码组件。6. 进阶自检用 MediaSource 探针确认解码通道真的开了编出来的包到底支不支持某个 profile肉眼看点没点开视频太不靠谱——有的页面会自动降级到低分辨率重编码流看起来播了实际走的是别的路径。我现在的做法是在应用启动后往页面里注入一段探针脚本把结果打到日志里一眼就能看出解码能力边界。// 探针脚本逐条探测浏览器实际支持的 codec string // 返回结构直接序列化到 CEF 的 console 日志里 (function () { const probes [ video/mp4; codecsavc1.42E01E, // H.264 Baseline video/mp4; codecsavc1.64001F, // H.264 High video/mp4; codecshvc1.1.6.L93.B0, // H.265 Mainhvc1 封装 video/mp4; codecshev1.1.6.L93.B0, // H.265 Mainhev1 封装 audio/mp4; codecsmp4a.40.2 // AAC-LC常被顺手忽略 ]; const result probes.map(function (type) { if (typeof MediaSource ! undefined MediaSource.isTypeSupported) { return { type: type, mse: MediaSource.isTypeSupported(type) }; } return { type: type, mse: null }; }); // 输出成单行方便 CEF 的 OnConsoleMessage 抓取 console.log([CODEC_PROBE] JSON.stringify(result)); })();MediaSource.isTypeSupported 比 canPlayType 更严格它走的是 MSE 的完整 codec 解析路径返回 false 基本就说明这条路走不通。avc1.42E01E 和 avc1.64001F 分别对应 Baseline 和 High profile很多监控流是 Baseline普通视频是 High两个都测才有意义。H.265 要同时测 hvc1 和 hev1前者是带参数集的标准封装后者允许参数集在带外不同来源的文件封装方式不一样只测一个容易得出错误结论。AAC 那条别省音频编解码器缺失时视频画面正常但没声音很容易被当成播放器 bug。C 侧接住这条日志// 在 CefRenderProcessHandler 或 CefDisplayHandler 里捕获探针输出 void OnConsoleMessage(CefRefPtrCefBrowser browser, cef_log_severity_t level, const CefString message, const CefString source, int line) override { std::string msg message.ToString(); // 只落探针日志避免刷屏 if (msg.rfind([CODEC_PROBE], 0) 0) { LOG(INFO) codec capability: msg; } }rfind 的第二个参数 0 表示从开头匹配等价于 startsWith比 substr 比较省一次拷贝。把这段接到自己的日志系统里每次发版前跑一遍解码能力的回归问题就跑不掉了。还有一个值得养成的习惯用 --disable-gpu 和默认参数各跑一次探针两次结果对比能直接告诉你硬解通道有没有起来。如果两次都返回 false是编解码器没编进去默认参数 false 但禁 GPU 后 true是硬解通路的问题反过来则是软解缺失。这个二分法比看日志猜快得多。从那以后我每次拿到一个新编的 libcef.dll不管是自己编的还是别人给的第一件事就是跑这个探针页把五个 codec string 的结果记在发布清单里不再靠肉眼点开视频看有没有画面。血泪经验是肉眼能播和真正支持是两码事。希望帮到你。本文还有配套的精品资源点击获取
