做Win32桌面开发的人基本都绕不过“程序里塞一个网页”这种需求。早些年大家用IE内核的WebBrowser控件卡顿、兼容性差、CSS3支持残缺做点现代前端的东西简直受罪。后来有人嵌CEF、嵌Electron功能是强了但安装包动不动几百MB更新还得跟着整个浏览器内核走维护成本非常高。WebView2的出现算是把这个问题解决了——它基于Chromium内核但运行时由系统级或应用级的Edge Runtime提供你不用把整个浏览器打包进自己程序里。这篇文章就用C在纯Win32工程里走一遍WebView2的集成流程从环境配置、最小可运行代码到C和前端页面的双向通信把关键步骤和踩过的坑都捋清楚。适合刚接触WebView2、想在传统Win32窗口里嵌入现代Web内容的开发者参考。1. WebView2 到底是什么为什么要在 Win32 里用它1.1 一句话讲清楚 WebView2 的定位WebView2 是微软推出的嵌入式浏览器控件底层用的是 Chromium 内核也就是 Microsoft Edge 现在用的那套渲染引擎。它不是一个独立的浏览器程序而是一组 COM 接口你可以把它理解成“一个可以被你程序直接调用的浏览器引擎”。在 Win32 里它以一个子窗口的形式嵌入到你的窗口内部你控制它的位置、大小、加载什么页面、何时执行脚本它则负责把网页内容渲染出来。这套东西的架构核心是进程分离。WebView2 运行的时候你的主程序是一个进程网页的渲染跑在独立的浏览器子进程里。这个设计带来的好处很直接——网页崩溃了不会把宿主程序带崩网页里卡死的脚本也不会阻塞你的UI线程。这对桌面应用来说是非常重要的稳定性保障。1.2 和传统 WebBrowser / CEF / Electron 比优势在哪我在项目里用过 WebBrowser 控件、CEFChromium Embedded Framework、也简单接触过 Electron 的壳对比下来 WebView2 的定位非常明显。先说 WebBrowser 控件。它封装的是 IE 内核从 IE7 到 IE11 一路兼容问题不断。前端项目用了个 ES6 语法IE 不支持用了 flex 布局表现不一致调一下远程调试根本没有。而且系统里的 IE 版本还会影响控件的实际渲染行为排查起来特别费劲。WebView2 不存在这个问题Chromium 内核的渲染能力和现在主流浏览器保持一致前端怎么写这里就怎么显示。再说 CEF。CEF 确实是方案功能强、可定制程度高但它有个致命问题——你要把整个 Chromium 内核以库的形式链接进你的程序编译时间以小时计最终产物体积轻松超过100MB。更新 Chromium 版本还需要重新编译整个工程。WebView2 是由 Edge Runtime 提供的安装 Edge 或单独安装运行时后你的程序直接调用即可几十KB 的代码就能获得完整的浏览器能力。Electron 则是“用 Web 技术写桌面应用”的框架本质上把 Node.js 和 Chromium 都打包进去了安装包体积通常200MB起步。如果是想给现有 Win32 程序加一个网页模块用 Electron 属于“为了喝瓶牛奶买头牛”。WebView2 可以非常轻量地嵌入到已存在的原生窗口中不需要改变整个项目的架构。1.3 什么时候不该用 WebView2也不是所有场景都该选 WebView2。如果你的目标系统是 Windows 7 且不想额外安装运行时WebView2 的支持范围有限旧系统上还是用 CEF 更稳。如果你的应用有极强的自定义浏览器行为需求比如深度修改渲染进程的沙箱策略、自定义网络层、拦截和改写所有请求到协议级别CEF 的灵活度仍然更高。WebView2 提供了一套相对完整的API但它的边界是“微软允许你做的那些事”而不是“Chromium 能做的所有事”。另外如果你的软件需要在完全离线、无Edge运行时且不允许安装任何额外组件的环境中运行WebView2 的固定版本模式可以解决但部署复杂度会上升。这个下面会聊到。2. 动手前的准备运行时和 SDK 到底怎么配2.1 WebView2 Runtime 的两种形态常青版与固定版很多人第一次接触 WebView2 都会被两个概念绕晕常青版Evergreen和固定版本Fixed Version。简单说常青版就是由微软自动更新的运行时用户装了 Edge 浏览器后系统里通常就已经有了。固定版本则是把某个特定版本的运行时文件随你的应用分发你完全掌握版本更新节奏。我在实际项目里建议优先用常青版因为安全补丁和功能升级都是自动的省心。但它有个前提目标机器上得有这个运行时。所以如果是面向普通用户发布的应用需要引导用户安装常青版运行时或者在安装包里带上离线安装包。微软官方提供了 WebView2 Runtime 的下载渠道分为在线引导安装包和离线安装包两种离线包里又分 x86、x64 和 ARM64 架构不能选错。固定版本适合那种对稳定性要求极高、不允许运行时自动更新的行业应用比如工控设备、医疗仪器上的软件。用固定版本时你需要下载对应的 NuGet 包或CAB包把 runtime 文件放进应用目录然后通过环境变量或注册表告诉 WebView2 去哪找这些文件。固定版本不随 Edge 更新所有版本行为完全可控但相应地安全更新也需要你自己跟进。2.2 获取 SDK 的两种方式NuGet 与手动下载SDK 就是你在代码里 include 的头文件和链接的库文件。最简单的获取方式是使用 NuGet 包Microsoft.Web.WebView2。在 Visual Studio 里右键项目选择“管理 NuGet 程序包”搜索安装即可。NuGet 包会自动把头文件、lib 库和依赖项都配置好还会在项目属性里加上必要的 include 路径和链接库路径省掉了不少手工配置的麻烦。如果你不想用 NuGet——比如你的构建环境是纯命令行、或者公司内网不允许访问 NuGet——也可以从微软官网手动下载 WebView2 SDK。下载下来是一个压缩包解压后里面有build\native\include头文件目录和build\native\lib对应架构的lib目录。拿到手后在项目设置里手动添加 include 目录和 lib 目录再把WebView2.lib加到链接器输入里。还有一个需要注意的地方SDK 版本和运行时版本存在兼容关系。新版 SDK 调用的一些API在旧版运行时上可能不存在运行时会返回HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。所以 SDK 版本不要追太新除非你明确知道目标机器上的运行时版本足够新。我个人的习惯是 SDK 版本比运行时版本滞后一点点稳定性反而更好。2.3 工程配置头文件与链接库工程配置这里有两个容易踩的坑。第一字符集必须统一。WebView2 的API几乎都是宽字符版本接口名带W后缀或者直接就是LPCWSTR参数所以你的工程建议设置为“使用 Unicode 字符集”同时代码里所有字符串常量都用L前缀。第二链接库不能少。即便是通过 NuGet 安装有些时候也需要手动确认链接器设置里有没有WebView2.lib。如果你用的是 CMake则需要在target_link_libraries里显式加上它。另外还要说明一点WebView2.lib只是一个导入库里面存的是跳转信息真正的实现还是靠运行时 DLL 提供的所以程序运行时仍然依赖目标机器上的 WebView2 Runtime。3. 最小可运行工程把一个网页塞进 Win32 窗口3.1 先搭一个最简单的 Win32 窗口骨架技术上说WebView2 涉及 COM 接口整个初始化是异步的所以代码结构上要比“创建一个窗口然后显示”复杂一些。但基本框架还是那个经典套路注册窗口类、创建窗口、进入消息循环。我建议用一个空项目起步新建一个.cpp文件先用纯 Win32 API 把窗口拉起来不要急着加 WebView2。确认窗口能正常显示、能响应关闭事件之后再逐步集成 WebView2这样排查问题会容易很多。窗口的创建过程很简单用RegisterClassEx注册窗口类指定窗口过程WndProc然后调用CreateWindowEx创建窗口显示并更新。消息循环用GetMessage/TranslateMessage/DispatchMessage的标准组合。这个过程有几个细节值得注意。窗口过程里要处理WM_SIZE因为 WebView2 创建后需要跟随窗口大小变化调整自身尺寸。WM_DESTROY里要释放 WebView2 相关资源再调用PostQuitMessage(0)让消息循环退出。3.2 初始化 COM 与创建 WebView2 环境WebView2 是基于 COM 的所以在调用任何 WebView2 接口之前必须先把 COM 初始化。建议使用CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED)。这里有个容易出错的地方很多人习惯在WinMain开头初始化 COM这个没问题但要注意初始化的线程和你后续调用 WebView2 接口的线程必须是同一个线程。WebView2 的回调默认在线程池线程上触发但你创建的 controller 和 webview 对象必须在同一个公寓线程里使用。简单说不要在后台线程里去操作你在主线程创建的 webview 对象否则会引发各种奇奇怪怪的崩溃。COM 初始化完成后调用CreateCoreWebView2EnvironmentWithOptions创建环境。这个函数是异步的它接收一个回调函数当环境创建完成时会被调用。环境对象ICoreWebView2Environment代表了一个运行环境它负责管理用户数据文件夹、运行时版本等配置。这个函数的签名是这样的HRESULT CreateCoreWebView2EnvironmentWithOptions( PCWSTR browserExecutableFolder, // 固定版本时指定路径常青版传 nullptr PCWSTR userDataFolder, // 用户数据目录传 nullptr 使用默认 ICoreWebView2EnvironmentOptions* options, // 额外选项可传 nullptr ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler* handler); // 完成回调常规开发中前三个参数直接传nullptr就行。这样 WebView2 会自动寻找系统中的常青版运行时并把用户数据放在默认位置。如果你用的是固定版本第一个参数要传固定版本运行时所在的目录路径。3.3 创建控制器并绑定父窗口环境创建成功后下一步是在你的窗口上创建一个“控制器”。控制器ICoreWebView2Controller相当于 WebView2 的“壳”它负责维护窗口绑定、尺寸、可见性等布局属性而真正的网页操作能力在ICoreWebView2接口上通过controller-get_CoreWebView2(webview)获取。在创建控制器的回调里你需要传入目标窗口的句柄hWnd。WebView2 会在这个窗口上创建一个子窗口用于渲染网页内容。创建完成后要立刻设置控制器的初始位置和大小否则网页区域可能显示不出来或者尺寸为0。设置尺寸的代码是RECT bounds; GetClientRect(hWnd, bounds); controller-put_Bounds(bounds);这一步很关键很多人第一次看到黑屏或者空白窗口往往就是忘了设置 bounds。3.4 导航到目标页面拿到ICoreWebView2接口后就可以调用Navigate方法加载网页了。它接收一个LPCWSTR类型的 URL。你可以加载一个在线地址比如Lhttps://www.bing.com也可以加载本地 HTML 文件的file://协议路径或者直接用NavigateToString方法加载一段 HTML 字符串。我实际开发时最常用的是先加载本地 HTML 文件等页面加载完成后再和 C 代码通信。这样调试方便也不用担心网络限制。本地 HTML 文件记得设置编码为 UTF-8推荐使用带 BOM 的格式否则中文在部分场景下可能乱码。导航是异步的Navigate调用后立刻返回实际页面加载和渲染在后台进行。如果需要知道页面何时加载完成要监听NavigationCompleted事件。这个事件在后面讲事件处理时细说。3.5 完整代码示例把上面几段组合起来就是一个最小可运行工程。这段代码我直接用来做过原型验证在 Visual Studio 2022 的空 C 项目里通过。#include windows.h #include wrl/client.h #include wrl/callback.h #include webview2.h #include string using namespace Microsoft::WRL; // 全局对象方便在窗口过程和回调中使用 ComPtrICoreWebView2Controller webviewController; ComPtrICoreWebView2 webview; // 窗口过程 LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { switch (message) { case WM_SIZE: // 窗口大小变化时同步调整 WebView2 的尺寸 if (webviewController ! nullptr) { RECT bounds; GetClientRect(hWnd, bounds); webviewController-put_Bounds(bounds); } return 0; case WM_DESTROY: // 关闭控制器释放资源 if (webviewController ! nullptr) { webviewController-Close(); } PostQuitMessage(0); return 0; } return DefWindowProc(hWnd, message, wParam, lParam); } int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE, PWSTR, int nCmdShow) { // 注册窗口类 const wchar_t CLASS_NAME[] LWebView2SampleWindow; WNDCLASS wc {}; wc.lpfnWndProc WndProc; wc.hInstance hInstance; wc.lpszClassName CLASS_NAME; wc.hCursor LoadCursor(nullptr, IDC_ARROW); RegisterClass(wc); // 创建窗口 HWND hWnd CreateWindowEx( 0, CLASS_NAME, LWebView2 Win32 Demo, WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, 1024, 768, nullptr, nullptr, hInstance, nullptr); if (!hWnd) { return 1; } ShowWindow(hWnd, nCmdShow); UpdateWindow(hWnd); // 初始化 COM HRESULT hr CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED); if (FAILED(hr)) { return 1; } // 创建 WebView2 环境并异步创建控制器 hr CreateCoreWebView2EnvironmentWithOptions( nullptr, nullptr, nullptr, CallbackICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler( [hWnd](HRESULT result, ICoreWebView2Environment* env) - HRESULT { if (FAILED(result)) { return result; } return env-CreateCoreWebView2Controller( hWnd, CallbackICoreWebView2CreateCoreWebView2ControllerCompletedHandler( [hWnd](HRESULT result, ICoreWebView2Controller* controller) - HRESULT { if (FAILED(result)) { return result; } webviewController controller; webviewController-get_CoreWebView2(webview); // 设置初始尺寸 RECT bounds; GetClientRect(hWnd, bounds); webviewController-put_Bounds(bounds); // 加载一个页面 webview-Navigate(Lhttps://www.bing.com); return S_OK; }).Get()); }).Get()); if (FAILED(hr)) { CoUninitialize(); return 1; } // 消息循环 MSG msg {}; while (GetMessage(msg, nullptr, 0, 0)) { TranslateMessage(msg); DispatchMessage(msg); } CoUninitialize(); return 0; }这段代码的逻辑非常直白创建窗口、初始化 COM、创建 WebView2 环境、异步创建控制器、绑定窗口、设置尺寸、加载网页、进入消息循环。我第一次跑通时看到 Bing 首页在自己的原生窗口里刷出来的瞬间还是很有成就感的。要注意代码里用了ComPtr来管理 COM 对象生命周期这样省去了手动Release的麻烦。另外Callback模板来自wrl/callback.h如果你用过 Windows Runtime 的异步操作对这个模板应该不陌生。4. 从“能跑”到“好用”双向通信与事件处理4.1 原生调前端ExecuteScript 的两种姿势WebView2 嵌入页面之后最常用的需求就是让 C 代码去操控页面的 DOM 或者执行页面里的 JS 函数。实现这个动作的核心方法是ICoreWebView2::ExecuteScript。webview-ExecuteScript(Ldocument.getElementById(status).innerText Hello from C;, nullptr);ExecuteScript接收一个 JS 代码字符串它会在页面上下文中执行这段代码。执行是异步的第二个参数是回调可以接收执行结果。如果你不需要结果传nullptr是可以的但注意传nullptr时无法判断执行是否失败。有时候你需要在页面里执行一段带参数的 JS 函数。常见的做法是拼接字符串但一定要注意转义。比如std::wstring param Lthis is a test; std::wstring script LshowMessage( param L);; webview-ExecuteScript(script.c_str(), nullptr);这段代码在param里如果含有单引号、反斜杠或者换行符页面端就会报语法错误。更稳妥的方式是用JSON.stringify生成合法的 JS 字符串字面量再拼进去。这一点我在早期开发时栽过跟头页面直接报SyntaxError排查了半天才发现是字符串转义的问题。如果要在页面加载完成后才执行脚本一定要等NavigationCompleted事件触发后再调用ExecuteScript否则脚本可能被执行在一个空文档上。这是新手比较容易忽略的细节。4.2 前端调原生PostWebMessageAsJson 与 WebMessageReceivedC 调 JS 是 ExecuteScript反向的 JS 调 C 则要依赖消息机制。WebView2 提供了一套方式在页面里用window.chrome.webview.postMessage发送消息C 端通过add_WebMessageReceived监听。前端页面里这样写window.chrome.webview.postMessage(hello from js); window.chrome.webview.postMessage({ type: saveData, value: 12345 });注意postMessage可以传字符串也可以传 JSON 对象。传对象时WebView2 内部会把它序列化成 JSON 字符串。C 端监听消息webview-add_WebMessageReceived( CallbackICoreWebView2WebMessageReceivedEventHandler( [](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args) - HRESULT { LPWSTR message nullptr; args-TryGetWebMessageAsString(message); if (message ! nullptr) { // message 是一个宽字符串保存着前端发来的内容 OutputDebugString(message); CoTaskMemFree(message); // 千万别忘这个内存是 COM 分配的 } return S_OK; }).Get(), nullptr);这里有个需要注意的点TryGetWebMessageAsString返回的LPWSTR内存需要调用CoTaskMemFree释放否则每次消息都会泄漏一块内存。很多人在高频通信场景下内存涨得飞快多半就是这个原因。另外这个回调里拿到的 message 就是前端发送的 JSON 字符串你可以用std::wstring保存然后解析。如果项目里没有 JSON 解析库可以用webview-PostWebMessageAsJson回传 JSON 给前端配合前端window.chrome.webview.addEventListener(message, ...)事件来接收。4.3 导航事件与页面加载状态除了消息通信WebView2 的导航事件也是高频使用的东西。NavigationStarting在导航开始时触发NavigationCompleted在导航完成后触发。我用这两个事件做过一个简单的加载提示页面开始加载时窗口标题加上“加载中”完成后再去掉。NavigationStarting 事件里可以做很多事情比如根据 URL 判断是否允许导航webview-add_NavigationStarting( CallbackICoreWebView2NavigationStartingEventHandler( [](ICoreWebView2* sender, ICoreWebView2NavigationStartingEventArgs* args) - HRESULT { // 获取目标 URL LPWSTR uri nullptr; args-get_Uri(uri); if (uri ! nullptr) { std::wstring url(uri); // 如果检测到某些域名不在白名单里可以取消导航 // args-put_Cancel(true); CoTaskMemFree(uri); } return S_OK; }).Get(), nullptr);注意put_Cancel(true)可以中断导航这个对做“外链只能在系统浏览器打开”之类的功能非常好用。在导航回调里获取到 URL 后如果不想在 WebView 里打开可以调用ShellExecute打开外部浏览器然后取消导航。4.4 窗口大小变化时的适配Win32 窗口是可以缩放尺寸的如果不处理WM_SIZEWebView2 的渲染区域就会停在创建时的大小窗口拉大了页面只有左上角一小块窗口缩小了网页又会被裁掉。这个前面的示例代码里已经写了核心代码就是把GetClientRect拿到的客户区尺寸设置给 controller 的Bounds属性。这个处理有几个细节。第一WM_SIZE在窗口创建的时候就会触发一次但那时 controller 可能还没创建完所以代码里要判空。第二如果你的窗口有菜单栏、工具栏或者状态栏GetClientRect拿到的已经是扣除这些区域后的客户区尺寸WebView2 的 bounds 应该填这个值而不是窗口的完整尺寸。第三如果你用了 DPI 缩放需要在WM_DPICHANGED里重新计算尺寸否则在高 DPI 屏幕上 WebView2 的页面会显得模糊或者尺寸不对。5. 踩坑实录与排查清单5.1 报错“Could not find the WebView2 Runtime”这个提示是刚接触 WebView2 时最容易撞上的一个错误。它的完整形式一般是Could not find the WebView2 Runtime. Make sure it is installed or download it from ...出现这个错误说明目标机器上没有安装 WebView2 Runtime或者程序没有找到它。解决办法分情况。如果只是开发机遇到这个问题通常是因为你安装的 Windows 版本里没有预装 Edge或者 Edge 被精简了。去微软官网下载 WebView2 Runtime 常青版安装包装上即可x86 和 x64 版本按系统架构选。如果发布软件给用户时出现这个提示那就是典型的部署问题。建议在安装包程序里检测注册表或运行时版本号如果缺失则静默安装离线包。离线包的体积大概一百多MB用户机器网络不好的时候这个体积不可小觑所以有条件的话尽量在安装时检测而不是直接带上。5.2 回调不执行 / 界面卡死WebView2 的回调没有触发最常见的两个原因。第一消息循环没有跑起来。WebView2 的回调分发依赖 Windows 消息循环如果你在初始化后立刻调用Sleep阻塞了主线程或者写了一个卡死的while循环回调自然永远不会执行。第二你访问了错误的线程。环境创建、控制器创建这些异步回调的线程模型是有讲究的在回调里操作 COM 代理对象如果不匹配公寓模型也有可能导致卡死。我之前遇到过一种情况在WM_CREATE里调用CreateCoreWebView2EnvironmentWithOptions但窗口还没显示出来就进入了一个阻塞式的初始化逻辑结果界面一直是空白的。后来把初始化动作拆到WM_CREATE之后用PostMessage延迟执行才解决。核心思路是别在主线程上做任何长时间的同步等待该异步的异步该回调的回调。5.3 关闭窗口时崩溃关闭窗口时崩溃多半是资源释放顺序出错了。正确顺序是先调用controller-Close()并置空webview和controller再退出消息循环最后CoUninitialize。如果反过来先释放了 COM 再调用 controller 的方法就会出现访问已释放对象的崩溃报错通常是0xC0000005访问冲突。另一个常见的坑是WM_DESTROY里释放 controller但回调或导航事件还在触发。比如页面里还有未完成的脚本执行controller 已经 Close 了这时候再调用接口就会出错。稳妥的做法是加一个closing标志位在WM_CLOSE里先通知 WebView2 停止一切活动再进入销毁流程。5.4 常见问题速查表现象可能原因处理方法启动报错找不到Runtime目标机未装WebView2 Runtime安装常青版或固定版运行时窗口空白网页不显示未设置controller Bounds或父窗口尺寸为0在创建成功后立刻put_Bounds网页显示但点击无响应控制器尺寸与窗口客户区不匹配在WM_SIZE中同步put_BoundsJS调用C消息收不到页面没有使用window.chrome.webview.postMessage检查是否正确书写前端APIC调用JS不执行页面还没加载完成在NavigationCompleted后执行关闭窗口崩溃资源释放顺序错误先Close controller再退出COM回调不触发消息循环阻塞或线程错误保持主线程消息循环运行高DPI下网页模糊未处理DPI缩放处理WM_DPICHANGED并更新bounds64位系统安装32位离线包报错架构不匹配安装对应架构的runtime这个表格基本覆盖了我开发过程中遇到的大部分问题。如果你碰到的情况不在表里还有一个排查技巧在CreateCoreWebView2EnvironmentWithOptions的回调参数里result会直接返回错误码用_com_error转成描述文字往往能定位到具体是哪一步出了问题。根据我个人经验WebView2 在 Win32 里的集成难度不算高只要理解了“环境-控制器-WebView对象”这三层关系以及“所有操作都是异步回调”这个核心机制整个开发就顺了。最花时间的部分反而是业务层的设计比如 C 和前端之间到底要定什么样的消息协议、如何处理页面和原生的生命周期同步。建议你在动手写代码之前先想清楚页面和原生各负责什么、消息格式怎么定义这会比写完再改省下很多时间。如果只是想快速验证 WebView2 的能力拿这份示例代码跑通一个本地 HTML 页面是个不错的起点。
Win32嵌入WebView2：从环境配置到C++与前端双向通信
做Win32桌面开发的人基本都绕不过“程序里塞一个网页”这种需求。早些年大家用IE内核的WebBrowser控件卡顿、兼容性差、CSS3支持残缺做点现代前端的东西简直受罪。后来有人嵌CEF、嵌Electron功能是强了但安装包动不动几百MB更新还得跟着整个浏览器内核走维护成本非常高。WebView2的出现算是把这个问题解决了——它基于Chromium内核但运行时由系统级或应用级的Edge Runtime提供你不用把整个浏览器打包进自己程序里。这篇文章就用C在纯Win32工程里走一遍WebView2的集成流程从环境配置、最小可运行代码到C和前端页面的双向通信把关键步骤和踩过的坑都捋清楚。适合刚接触WebView2、想在传统Win32窗口里嵌入现代Web内容的开发者参考。1. WebView2 到底是什么为什么要在 Win32 里用它1.1 一句话讲清楚 WebView2 的定位WebView2 是微软推出的嵌入式浏览器控件底层用的是 Chromium 内核也就是 Microsoft Edge 现在用的那套渲染引擎。它不是一个独立的浏览器程序而是一组 COM 接口你可以把它理解成“一个可以被你程序直接调用的浏览器引擎”。在 Win32 里它以一个子窗口的形式嵌入到你的窗口内部你控制它的位置、大小、加载什么页面、何时执行脚本它则负责把网页内容渲染出来。这套东西的架构核心是进程分离。WebView2 运行的时候你的主程序是一个进程网页的渲染跑在独立的浏览器子进程里。这个设计带来的好处很直接——网页崩溃了不会把宿主程序带崩网页里卡死的脚本也不会阻塞你的UI线程。这对桌面应用来说是非常重要的稳定性保障。1.2 和传统 WebBrowser / CEF / Electron 比优势在哪我在项目里用过 WebBrowser 控件、CEFChromium Embedded Framework、也简单接触过 Electron 的壳对比下来 WebView2 的定位非常明显。先说 WebBrowser 控件。它封装的是 IE 内核从 IE7 到 IE11 一路兼容问题不断。前端项目用了个 ES6 语法IE 不支持用了 flex 布局表现不一致调一下远程调试根本没有。而且系统里的 IE 版本还会影响控件的实际渲染行为排查起来特别费劲。WebView2 不存在这个问题Chromium 内核的渲染能力和现在主流浏览器保持一致前端怎么写这里就怎么显示。再说 CEF。CEF 确实是方案功能强、可定制程度高但它有个致命问题——你要把整个 Chromium 内核以库的形式链接进你的程序编译时间以小时计最终产物体积轻松超过100MB。更新 Chromium 版本还需要重新编译整个工程。WebView2 是由 Edge Runtime 提供的安装 Edge 或单独安装运行时后你的程序直接调用即可几十KB 的代码就能获得完整的浏览器能力。Electron 则是“用 Web 技术写桌面应用”的框架本质上把 Node.js 和 Chromium 都打包进去了安装包体积通常200MB起步。如果是想给现有 Win32 程序加一个网页模块用 Electron 属于“为了喝瓶牛奶买头牛”。WebView2 可以非常轻量地嵌入到已存在的原生窗口中不需要改变整个项目的架构。1.3 什么时候不该用 WebView2也不是所有场景都该选 WebView2。如果你的目标系统是 Windows 7 且不想额外安装运行时WebView2 的支持范围有限旧系统上还是用 CEF 更稳。如果你的应用有极强的自定义浏览器行为需求比如深度修改渲染进程的沙箱策略、自定义网络层、拦截和改写所有请求到协议级别CEF 的灵活度仍然更高。WebView2 提供了一套相对完整的API但它的边界是“微软允许你做的那些事”而不是“Chromium 能做的所有事”。另外如果你的软件需要在完全离线、无Edge运行时且不允许安装任何额外组件的环境中运行WebView2 的固定版本模式可以解决但部署复杂度会上升。这个下面会聊到。2. 动手前的准备运行时和 SDK 到底怎么配2.1 WebView2 Runtime 的两种形态常青版与固定版很多人第一次接触 WebView2 都会被两个概念绕晕常青版Evergreen和固定版本Fixed Version。简单说常青版就是由微软自动更新的运行时用户装了 Edge 浏览器后系统里通常就已经有了。固定版本则是把某个特定版本的运行时文件随你的应用分发你完全掌握版本更新节奏。我在实际项目里建议优先用常青版因为安全补丁和功能升级都是自动的省心。但它有个前提目标机器上得有这个运行时。所以如果是面向普通用户发布的应用需要引导用户安装常青版运行时或者在安装包里带上离线安装包。微软官方提供了 WebView2 Runtime 的下载渠道分为在线引导安装包和离线安装包两种离线包里又分 x86、x64 和 ARM64 架构不能选错。固定版本适合那种对稳定性要求极高、不允许运行时自动更新的行业应用比如工控设备、医疗仪器上的软件。用固定版本时你需要下载对应的 NuGet 包或CAB包把 runtime 文件放进应用目录然后通过环境变量或注册表告诉 WebView2 去哪找这些文件。固定版本不随 Edge 更新所有版本行为完全可控但相应地安全更新也需要你自己跟进。2.2 获取 SDK 的两种方式NuGet 与手动下载SDK 就是你在代码里 include 的头文件和链接的库文件。最简单的获取方式是使用 NuGet 包Microsoft.Web.WebView2。在 Visual Studio 里右键项目选择“管理 NuGet 程序包”搜索安装即可。NuGet 包会自动把头文件、lib 库和依赖项都配置好还会在项目属性里加上必要的 include 路径和链接库路径省掉了不少手工配置的麻烦。如果你不想用 NuGet——比如你的构建环境是纯命令行、或者公司内网不允许访问 NuGet——也可以从微软官网手动下载 WebView2 SDK。下载下来是一个压缩包解压后里面有build\native\include头文件目录和build\native\lib对应架构的lib目录。拿到手后在项目设置里手动添加 include 目录和 lib 目录再把WebView2.lib加到链接器输入里。还有一个需要注意的地方SDK 版本和运行时版本存在兼容关系。新版 SDK 调用的一些API在旧版运行时上可能不存在运行时会返回HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)。所以 SDK 版本不要追太新除非你明确知道目标机器上的运行时版本足够新。我个人的习惯是 SDK 版本比运行时版本滞后一点点稳定性反而更好。2.3 工程配置头文件与链接库工程配置这里有两个容易踩的坑。第一字符集必须统一。WebView2 的API几乎都是宽字符版本接口名带W后缀或者直接就是LPCWSTR参数所以你的工程建议设置为“使用 Unicode 字符集”同时代码里所有字符串常量都用L前缀。第二链接库不能少。即便是通过 NuGet 安装有些时候也需要手动确认链接器设置里有没有WebView2.lib。如果你用的是 CMake则需要在target_link_libraries里显式加上它。另外还要说明一点WebView2.lib只是一个导入库里面存的是跳转信息真正的实现还是靠运行时 DLL 提供的所以程序运行时仍然依赖目标机器上的 WebView2 Runtime。3. 最小可运行工程把一个网页塞进 Win32 窗口3.1 先搭一个最简单的 Win32 窗口骨架技术上说WebView2 涉及 COM 接口整个初始化是异步的所以代码结构上要比“创建一个窗口然后显示”复杂一些。但基本框架还是那个经典套路注册窗口类、创建窗口、进入消息循环。我建议用一个空项目起步新建一个.cpp文件先用纯 Win32 API 把窗口拉起来不要急着加 WebView2。确认窗口能正常显示、能响应关闭事件之后再逐步集成 WebView2这样排查问题会容易很多。窗口的创建过程很简单用RegisterClassEx注册窗口类指定窗口过程WndProc然后调用CreateWindowEx创建窗口显示并更新。消息循环用GetMessage/TranslateMessage/DispatchMessage的标准组合。这个过程有几个细节值得注意。窗口过程里要处理WM_SIZE因为 WebView2 创建后需要跟随窗口大小变化调整自身尺寸。WM_DESTROY里要释放 WebView2 相关资源再调用PostQuitMessage(0)让消息循环退出。3.2 初始化 COM 与创建 WebView2 环境WebView2 是基于 COM 的所以在调用任何 WebView2 接口之前必须先把 COM 初始化。建议使用CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED)。这里有个容易出错的地方很多人习惯在WinMain开头初始化 COM这个没问题但要注意初始化的线程和你后续调用 WebView2 接口的线程必须是同一个线程。WebView2 的回调默认在线程池线程上触发但你创建的 controller 和 webview 对象必须在同一个公寓线程里使用。简单说不要在后台线程里去操作你在主线程创建的 webview 对象否则会引发各种奇奇怪怪的崩溃。COM 初始化完成后调用CreateCoreWebView2EnvironmentWithOptions创建环境。这个函数是异步的它接收一个回调函数当环境创建完成时会被调用。环境对象ICoreWebView2Environment代表了一个运行环境它负责管理用户数据文件夹、运行时版本等配置。这个函数的签名是这样的HRESULT CreateCoreWebView2EnvironmentWithOptions( PCWSTR browserExecutableFolder, // 固定版本时指定路径常青版传 nullptr PCWSTR userDataFolder, // 用户数据目录传 nullptr 使用默认 ICoreWebView2EnvironmentOptions* options, // 额外选项可传 nullptr ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler* handler); // 完成回调常规开发中前三个参数直接传nullptr就行。这样 WebView2 会自动寻找系统中的常青版运行时并把用户数据放在默认位置。如果你用的是固定版本第一个参数要传固定版本运行时所在的目录路径。3.3 创建控制器并绑定父窗口环境创建成功后下一步是在你的窗口上创建一个“控制器”。控制器ICoreWebView2Controller相当于 WebView2 的“壳”它负责维护窗口绑定、尺寸、可见性等布局属性而真正的网页操作能力在ICoreWebView2接口上通过controller-get_CoreWebView2(webview)获取。在创建控制器的回调里你需要传入目标窗口的句柄hWnd。WebView2 会在这个窗口上创建一个子窗口用于渲染网页内容。创建完成后要立刻设置控制器的初始位置和大小否则网页区域可能显示不出来或者尺寸为0。设置尺寸的代码是RECT bounds; GetClientRect(hWnd, bounds); controller-put_Bounds(bounds);这一步很关键很多人第一次看到黑屏或者空白窗口往往就是忘了设置 bounds。3.4 导航到目标页面拿到ICoreWebView2接口后就可以调用Navigate方法加载网页了。它接收一个LPCWSTR类型的 URL。你可以加载一个在线地址比如Lhttps://www.bing.com也可以加载本地 HTML 文件的file://协议路径或者直接用NavigateToString方法加载一段 HTML 字符串。我实际开发时最常用的是先加载本地 HTML 文件等页面加载完成后再和 C 代码通信。这样调试方便也不用担心网络限制。本地 HTML 文件记得设置编码为 UTF-8推荐使用带 BOM 的格式否则中文在部分场景下可能乱码。导航是异步的Navigate调用后立刻返回实际页面加载和渲染在后台进行。如果需要知道页面何时加载完成要监听NavigationCompleted事件。这个事件在后面讲事件处理时细说。3.5 完整代码示例把上面几段组合起来就是一个最小可运行工程。这段代码我直接用来做过原型验证在 Visual Studio 2022 的空 C 项目里通过。#include windows.h #include wrl/client.h #include wrl/callback.h #include webview2.h #include string using namespace Microsoft::WRL; // 全局对象方便在窗口过程和回调中使用 ComPtrICoreWebView2Controller webviewController; ComPtrICoreWebView2 webview; // 窗口过程 LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { switch (message) { case WM_SIZE: // 窗口大小变化时同步调整 WebView2 的尺寸 if (webviewController ! nullptr) { RECT bounds; GetClientRect(hWnd, bounds); webviewController-put_Bounds(bounds); } return 0; case WM_DESTROY: // 关闭控制器释放资源 if (webviewController ! nullptr) { webviewController-Close(); } PostQuitMessage(0); return 0; } return DefWindowProc(hWnd, message, wParam, lParam); } int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE, PWSTR, int nCmdShow) { // 注册窗口类 const wchar_t CLASS_NAME[] LWebView2SampleWindow; WNDCLASS wc {}; wc.lpfnWndProc WndProc; wc.hInstance hInstance; wc.lpszClassName CLASS_NAME; wc.hCursor LoadCursor(nullptr, IDC_ARROW); RegisterClass(wc); // 创建窗口 HWND hWnd CreateWindowEx( 0, CLASS_NAME, LWebView2 Win32 Demo, WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, 1024, 768, nullptr, nullptr, hInstance, nullptr); if (!hWnd) { return 1; } ShowWindow(hWnd, nCmdShow); UpdateWindow(hWnd); // 初始化 COM HRESULT hr CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED); if (FAILED(hr)) { return 1; } // 创建 WebView2 环境并异步创建控制器 hr CreateCoreWebView2EnvironmentWithOptions( nullptr, nullptr, nullptr, CallbackICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler( [hWnd](HRESULT result, ICoreWebView2Environment* env) - HRESULT { if (FAILED(result)) { return result; } return env-CreateCoreWebView2Controller( hWnd, CallbackICoreWebView2CreateCoreWebView2ControllerCompletedHandler( [hWnd](HRESULT result, ICoreWebView2Controller* controller) - HRESULT { if (FAILED(result)) { return result; } webviewController controller; webviewController-get_CoreWebView2(webview); // 设置初始尺寸 RECT bounds; GetClientRect(hWnd, bounds); webviewController-put_Bounds(bounds); // 加载一个页面 webview-Navigate(Lhttps://www.bing.com); return S_OK; }).Get()); }).Get()); if (FAILED(hr)) { CoUninitialize(); return 1; } // 消息循环 MSG msg {}; while (GetMessage(msg, nullptr, 0, 0)) { TranslateMessage(msg); DispatchMessage(msg); } CoUninitialize(); return 0; }这段代码的逻辑非常直白创建窗口、初始化 COM、创建 WebView2 环境、异步创建控制器、绑定窗口、设置尺寸、加载网页、进入消息循环。我第一次跑通时看到 Bing 首页在自己的原生窗口里刷出来的瞬间还是很有成就感的。要注意代码里用了ComPtr来管理 COM 对象生命周期这样省去了手动Release的麻烦。另外Callback模板来自wrl/callback.h如果你用过 Windows Runtime 的异步操作对这个模板应该不陌生。4. 从“能跑”到“好用”双向通信与事件处理4.1 原生调前端ExecuteScript 的两种姿势WebView2 嵌入页面之后最常用的需求就是让 C 代码去操控页面的 DOM 或者执行页面里的 JS 函数。实现这个动作的核心方法是ICoreWebView2::ExecuteScript。webview-ExecuteScript(Ldocument.getElementById(status).innerText Hello from C;, nullptr);ExecuteScript接收一个 JS 代码字符串它会在页面上下文中执行这段代码。执行是异步的第二个参数是回调可以接收执行结果。如果你不需要结果传nullptr是可以的但注意传nullptr时无法判断执行是否失败。有时候你需要在页面里执行一段带参数的 JS 函数。常见的做法是拼接字符串但一定要注意转义。比如std::wstring param Lthis is a test; std::wstring script LshowMessage( param L);; webview-ExecuteScript(script.c_str(), nullptr);这段代码在param里如果含有单引号、反斜杠或者换行符页面端就会报语法错误。更稳妥的方式是用JSON.stringify生成合法的 JS 字符串字面量再拼进去。这一点我在早期开发时栽过跟头页面直接报SyntaxError排查了半天才发现是字符串转义的问题。如果要在页面加载完成后才执行脚本一定要等NavigationCompleted事件触发后再调用ExecuteScript否则脚本可能被执行在一个空文档上。这是新手比较容易忽略的细节。4.2 前端调原生PostWebMessageAsJson 与 WebMessageReceivedC 调 JS 是 ExecuteScript反向的 JS 调 C 则要依赖消息机制。WebView2 提供了一套方式在页面里用window.chrome.webview.postMessage发送消息C 端通过add_WebMessageReceived监听。前端页面里这样写window.chrome.webview.postMessage(hello from js); window.chrome.webview.postMessage({ type: saveData, value: 12345 });注意postMessage可以传字符串也可以传 JSON 对象。传对象时WebView2 内部会把它序列化成 JSON 字符串。C 端监听消息webview-add_WebMessageReceived( CallbackICoreWebView2WebMessageReceivedEventHandler( [](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args) - HRESULT { LPWSTR message nullptr; args-TryGetWebMessageAsString(message); if (message ! nullptr) { // message 是一个宽字符串保存着前端发来的内容 OutputDebugString(message); CoTaskMemFree(message); // 千万别忘这个内存是 COM 分配的 } return S_OK; }).Get(), nullptr);这里有个需要注意的点TryGetWebMessageAsString返回的LPWSTR内存需要调用CoTaskMemFree释放否则每次消息都会泄漏一块内存。很多人在高频通信场景下内存涨得飞快多半就是这个原因。另外这个回调里拿到的 message 就是前端发送的 JSON 字符串你可以用std::wstring保存然后解析。如果项目里没有 JSON 解析库可以用webview-PostWebMessageAsJson回传 JSON 给前端配合前端window.chrome.webview.addEventListener(message, ...)事件来接收。4.3 导航事件与页面加载状态除了消息通信WebView2 的导航事件也是高频使用的东西。NavigationStarting在导航开始时触发NavigationCompleted在导航完成后触发。我用这两个事件做过一个简单的加载提示页面开始加载时窗口标题加上“加载中”完成后再去掉。NavigationStarting 事件里可以做很多事情比如根据 URL 判断是否允许导航webview-add_NavigationStarting( CallbackICoreWebView2NavigationStartingEventHandler( [](ICoreWebView2* sender, ICoreWebView2NavigationStartingEventArgs* args) - HRESULT { // 获取目标 URL LPWSTR uri nullptr; args-get_Uri(uri); if (uri ! nullptr) { std::wstring url(uri); // 如果检测到某些域名不在白名单里可以取消导航 // args-put_Cancel(true); CoTaskMemFree(uri); } return S_OK; }).Get(), nullptr);注意put_Cancel(true)可以中断导航这个对做“外链只能在系统浏览器打开”之类的功能非常好用。在导航回调里获取到 URL 后如果不想在 WebView 里打开可以调用ShellExecute打开外部浏览器然后取消导航。4.4 窗口大小变化时的适配Win32 窗口是可以缩放尺寸的如果不处理WM_SIZEWebView2 的渲染区域就会停在创建时的大小窗口拉大了页面只有左上角一小块窗口缩小了网页又会被裁掉。这个前面的示例代码里已经写了核心代码就是把GetClientRect拿到的客户区尺寸设置给 controller 的Bounds属性。这个处理有几个细节。第一WM_SIZE在窗口创建的时候就会触发一次但那时 controller 可能还没创建完所以代码里要判空。第二如果你的窗口有菜单栏、工具栏或者状态栏GetClientRect拿到的已经是扣除这些区域后的客户区尺寸WebView2 的 bounds 应该填这个值而不是窗口的完整尺寸。第三如果你用了 DPI 缩放需要在WM_DPICHANGED里重新计算尺寸否则在高 DPI 屏幕上 WebView2 的页面会显得模糊或者尺寸不对。5. 踩坑实录与排查清单5.1 报错“Could not find the WebView2 Runtime”这个提示是刚接触 WebView2 时最容易撞上的一个错误。它的完整形式一般是Could not find the WebView2 Runtime. Make sure it is installed or download it from ...出现这个错误说明目标机器上没有安装 WebView2 Runtime或者程序没有找到它。解决办法分情况。如果只是开发机遇到这个问题通常是因为你安装的 Windows 版本里没有预装 Edge或者 Edge 被精简了。去微软官网下载 WebView2 Runtime 常青版安装包装上即可x86 和 x64 版本按系统架构选。如果发布软件给用户时出现这个提示那就是典型的部署问题。建议在安装包程序里检测注册表或运行时版本号如果缺失则静默安装离线包。离线包的体积大概一百多MB用户机器网络不好的时候这个体积不可小觑所以有条件的话尽量在安装时检测而不是直接带上。5.2 回调不执行 / 界面卡死WebView2 的回调没有触发最常见的两个原因。第一消息循环没有跑起来。WebView2 的回调分发依赖 Windows 消息循环如果你在初始化后立刻调用Sleep阻塞了主线程或者写了一个卡死的while循环回调自然永远不会执行。第二你访问了错误的线程。环境创建、控制器创建这些异步回调的线程模型是有讲究的在回调里操作 COM 代理对象如果不匹配公寓模型也有可能导致卡死。我之前遇到过一种情况在WM_CREATE里调用CreateCoreWebView2EnvironmentWithOptions但窗口还没显示出来就进入了一个阻塞式的初始化逻辑结果界面一直是空白的。后来把初始化动作拆到WM_CREATE之后用PostMessage延迟执行才解决。核心思路是别在主线程上做任何长时间的同步等待该异步的异步该回调的回调。5.3 关闭窗口时崩溃关闭窗口时崩溃多半是资源释放顺序出错了。正确顺序是先调用controller-Close()并置空webview和controller再退出消息循环最后CoUninitialize。如果反过来先释放了 COM 再调用 controller 的方法就会出现访问已释放对象的崩溃报错通常是0xC0000005访问冲突。另一个常见的坑是WM_DESTROY里释放 controller但回调或导航事件还在触发。比如页面里还有未完成的脚本执行controller 已经 Close 了这时候再调用接口就会出错。稳妥的做法是加一个closing标志位在WM_CLOSE里先通知 WebView2 停止一切活动再进入销毁流程。5.4 常见问题速查表现象可能原因处理方法启动报错找不到Runtime目标机未装WebView2 Runtime安装常青版或固定版运行时窗口空白网页不显示未设置controller Bounds或父窗口尺寸为0在创建成功后立刻put_Bounds网页显示但点击无响应控制器尺寸与窗口客户区不匹配在WM_SIZE中同步put_BoundsJS调用C消息收不到页面没有使用window.chrome.webview.postMessage检查是否正确书写前端APIC调用JS不执行页面还没加载完成在NavigationCompleted后执行关闭窗口崩溃资源释放顺序错误先Close controller再退出COM回调不触发消息循环阻塞或线程错误保持主线程消息循环运行高DPI下网页模糊未处理DPI缩放处理WM_DPICHANGED并更新bounds64位系统安装32位离线包报错架构不匹配安装对应架构的runtime这个表格基本覆盖了我开发过程中遇到的大部分问题。如果你碰到的情况不在表里还有一个排查技巧在CreateCoreWebView2EnvironmentWithOptions的回调参数里result会直接返回错误码用_com_error转成描述文字往往能定位到具体是哪一步出了问题。根据我个人经验WebView2 在 Win32 里的集成难度不算高只要理解了“环境-控制器-WebView对象”这三层关系以及“所有操作都是异步回调”这个核心机制整个开发就顺了。最花时间的部分反而是业务层的设计比如 C 和前端之间到底要定什么样的消息协议、如何处理页面和原生的生命周期同步。建议你在动手写代码之前先想清楚页面和原生各负责什么、消息格式怎么定义这会比写完再改省下很多时间。如果只是想快速验证 WebView2 的能力拿这份示例代码跑通一个本地 HTML 页面是个不错的起点。
