如果你还在 MFC 工程里用 IWebBrowser2 那个老掉牙的 IE 内核控件去加载 HTML，我建议你认真看看 WebView2。过去两年我陆陆续续把几个维护中的 MFC 项目的网页模块从 IE 控件迁移到了 WebView2，本地网页嵌入这块的体验可以说完全是两个时代。这篇文章就从一个实际项目的角度，把 WebView2 在 MFC 里的接入流程、完整代码、常见的坑一次讲清楚，适合正在用 VS2019 / VS2022 做桌面开发、想把本地 HTML 页面嵌进对话框或视图窗口的开发者。
先说一个身边的场景：你要做一个设备管理工具，左边是 MFC 的树形列表和按钮，右边是一块展示实时图表、操作指引、甚至带点交互动画的网页区域。用 IE 控件能跑，但稍微上点 CSS3 动画、Flex 布局、Canvas 绘图，各种兼容性问题就冒出来了。WebView2 基于 Chromium 内核，跟 Microsoft Edge 同源，现代 Web 的能力全都有。下面我就按实际接入顺序，把每一步怎么操作、代码怎么组织、遇到问题怎么排查，全部拆开讲。
1. 为什么 MFC 嵌入网页要选 WebView2 而不是老牌 IE 控件
1.1 IE 控件的历史包袱和核心痛点
MFC 里传统嵌入网页的方法是使用IWebBrowser2，对应的是微软的 MSHTML / Trident 内核。这个方案在 XP、Win7 时代还算能用，放到现在就很难受了。我自己踩过的坑包括：flex布局直接失效，position: sticky表现异常，ES6 语法不支持，更别提 WebSocket、Canvas 这些现代能力。除了渲染能力落后，IE 模式还有不少安全问题，尤其是 ActiveX 相关的漏洞和奇怪的默认权限设置，在安全审查时很容易被标记。微软官方早已停止 IE 内核的功能演进，继续用下去，网页代码写得越新，兼容成本越高。
有人想到一个变通方案，就是本机装了 Edge 或 Chrome，用命令行去启动浏览器窗口。这确实是个路子，但体验割裂，页面跳出了应用程序，数据交互也只能靠本地 HTTP 服务转发或者写临时文件，繁琐不说，还容易把简单的工具做成“浏览器套壳”。
1.2 WebView2 与 CEF、Electron 的取舍
既然要换，市面上也有几个替代方案。CEF（Chromium Embedded Framework）功能很强，但体积很大，通常一个 release 包光 dll 和资源文件就一两百 MB，编译和部署都比较折腾。Electron 适合直接做一个全新的桌面应用，但如果要把一个已有的 MFC 程序改造，等于重构整个外壳，成本太高。WebView2 的优势在于它复用系统里的 Microsoft Edge WebView2 Runtime，应用包体积增加很小，而且是微软官方维护，安全补丁跟随 Chromium 更新。这是我在 MFC 项目里选它的核心理由。
需要说明的是，WebView2 并不是把整个浏览器嵌入你的程序，而是提供了一套 COM 接口，把渲染引擎作为运行时组件加载。你可以把 WebView2 理解成“显卡驱动”类似的共享组件：系统里有 Runtime，你的程序就可以调用它；如果没有，程序就会在启动或初始化时报错。后面章节我会专门讲怎么排查 Runtime 缺失的问题。
1.3 WebView2 能解决哪些实际问题
从功能层面来说，WebView2 解决了三类核心问题：第一，渲染能力强，现代 Web 技术基本零成本迁移；第二，本地网页和原生 C++ 可以双向通信，通过PostWebMessageAsJson和WebMessageReceived事件就能互发 JSON 消息，没必要起本地 HTTP 服务；第三，虚拟主机名映射机制允许你把本地文件夹伪装成一个域名，这样网页里加载相对路径的资源、发起 fetch 请求、使用本地数据库，行为都跟部署在远程服务器上一致。这几个能力在做离线帮助文档、本地数据可视化面板、设备配置向导时非常实用。
2. 环境准备：Runtime、离线包与项目配置的完整清单
2.1 WebView2 Runtime 到底装在哪里
很多人第一次接触 WebView2，会在初始化时看到一行错误提示：Could not find the WebView2 runtime installation。这个报错十有八九是因为开发机或用户机器上没有安装 WebView2 Runtime。Runtime 有两种形态：一种是 Evergreen Runtime（常青模式），由微软自动更新，大多数 Windows 10 / Windows 11 系统上已经预置了；另一种是 Fixed Version（固定版本），把运行时文件放在应用目录下，版本由开发者完全控制，适合离线环境和需要严格版本一致的场景。
Evergreen 模式最简单，开发和测试阶段通常不用管，系统里有 Edge 浏览器就一般能用。但如果你做的工具要在 Windows Server、精简版系统或者离线内网里运行，就需要主动检测 Runtime 是否存在。用GetAvailableCoreWebView2BrowserVersionString可以查询当前可用的 Runtime 版本，返回空字符串说明没有可用运行时。这个 API 也帮你区分是全都缺失，还是架构不匹配，比如系统只装了 x64 的 Runtime，而你的程序是 x86 编译，也会出现找不到的情况。
2.2 离线安装包和固定版本部署
部署到客户机器时，我强烈建议把 WebView2 Runtime 作为安装前置条件。最简单的方式是在安装包里带上离线安装包（MicrosoftEdgeWebView2RuntimeInstallerX64.exe），安装时静默执行。如果客户环境完全无外网，就用 Fixed Version 模式，从微软官方下载独立运行时压缩包，解压到程序的某个子目录，初始化时把该目录完整路径传给CreateCoreWebView2EnvironmentWithOptions的第一个参数即可。
固定版本部署要注意版本目录的完整性，缺失任何一个 dll 都可能导致初始化失败。我的习惯是建立一个更新文件清单，记录版本号和文件大小，升级时自动校验。另外，Fixed Version 模式下微软不做自动更新，一旦网页代码用到了新特性，需要你手动下载新版本运行时替换。这对追求稳定和可控的工业软件来说反而是好事。
2.3 NuGet 包引用与头文件链路
在 Visual Studio 里给 MFC 项目接入 WebView2，最省心的是通过 NuGet 安装Microsoft.Web.WebView2包。安装完成后，项目会自动包含WebView2.h和WebView2LoaderStatic.lib，编译时不需要再手动配置额外的链接目录。我用的是 VS2022，如果你还在用 VS2019，NuGet 包一样兼容，只是要注意选择对应的平台版本。
NuGet 包会为不同平台生成不同的加载库文件，所以把解决方案平台从 Win32 切到 x64 时，如果出现链接错误，第一反应要去看 NuGet 是否重新还原了对应平台版本的包。另一个很容易踩的坑是宏冲突：WebView2 头文件依赖 Windows SDK，如果项目里定义了NOMINMAX和WIN32_LEAN_AND_MEAN，能减少不少编译麻烦。MFC 项目默认会有大量宏，我在实际项目里发现min/max宏和 WebView2 头文件里的 std 代码冲突很常见，所以在stdafx.h开头加上#define NOMINMAX会有用。
2.4 一个干净的项目配置清单
我整理了一份常用配置项，照着设置基本能避开 90% 的坑：
| 配置项 | 推荐值 | 说明 |
|---|---|---|
| 平台 | x64 | 如果目标机器都是 64 位系统，建议直接用 x64 |
| C++ 语言标准 | C++17 或以上 | 回调里大量使用 lambda，标准太老容易出问题 |
| 字符集 | Unicode | MFC 项目请务必保持 Unicode |
| 预处理定义 | NOMINMAX、WIN32_LEAN_AND_MEAN | 减少 Windows 头文件宏对 C++ 标准库的干扰 |
| NuGet 包 | Microsoft.Web.WebView2 | 用最新稳定版即可 |
| MFC 版本 | 使用共享 DLL | 减少静态链接带来的部署体积问题 |
确认好这些之后，就可以正式写代码了。
3. 核心代码：从初始化到加载本地网页的完整实现
3.1 两种创建方式的取舍
WebView2 在 MFC 项目里有两种创建方式。一种是比较新的CWebView2类，从 VS2022 的 MFC 版本（v17.4 之后）开始提供，它封装了大部分 COM 细节，代码很简洁，适合新项目；另一种是直接使用 COM 接口，通过CreateCoreWebView2EnvironmentWithOptions和CreateCoreWebView2Controller手动创建，可控性更强，适合需要自定义环境选项、用户数据目录、固定版本路径的老项目。
我的建议是：如果明确用 VS2022 且不打算回退，用CWebView2类会快很多。但如果你的项目需要迁移到旧编译器，或者需要精细控制环境参数，建议直接用 COM 方式。下面的代码我用 COM 方式写，因为它在不同编译器版本之间兼容性最好，也能让你理解 WebView2 的整套初始化流程。
3.2 在对话框或视图窗口中嵌入 WebView2
先演示在 MFC 对话框中嵌入 WebView2 的做法。核心是在对话框初始化时调用初始化函数，把this->GetSafeHwnd()传给环境创建函数，WebView2 会自动把渲染内容附加到这个窗口上。注意初始化是异步的，不能在OnInitDialog里同步等待控件就绪，要在回调函数里完成后续操作。
下面是一个完整的示例头文件：
// WebView2HostDlg.h #pragma once #include <afxwin.h> #include <WebView2.h> #include <wrl/client.h> class CWebView2HostDlg : public CDialogEx { public: CWebView2HostDlg(CWnd* pParent = nullptr); virtual ~CWebView2HostDlg(); enum { IDD = IDD_WEBVIEW2_HOST_DIALOG }; protected: virtual void DoDataExchange(CDataExchange* pDX); virtual BOOL OnInitDialog(); afx_msg void OnSize(UINT nType, int cx, int cy); afx_msg void OnDestroy(); afx_msg void OnBnClickedBtnLoadPage(); DECLARE_MESSAGE_MAP() private: void InitWebView2(); void ResizeWebView(); HRESULT OnWebViewCreated(Microsoft::WRL::ComPtr<ICoreWebView2Controller> controller); Microsoft::WRL::ComPtr<ICoreWebView2Controller> m_controller; Microsoft::WRL::ComPtr<ICoreWebView2> m_webView; Microsoft::WRL::ComPtr<ICoreWebView2Environment> m_environment; bool m_webViewReady = false; };3.3 初始化函数与异步回调的完整代码
对话框的.cpp文件里，重点是InitWebView2函数。这个函数先检查是否已经初始化过，然后创建环境，创建控制器，最后导航到本地页面。我在回调里用lambda捕获this指针，这里要注意：如果对话框可能提前销毁，务必在OnDestroy里做资源清理，否则异步回调可能访问到已经失效的窗口句柄。
void CWebView2HostDlg::InitWebView2() { if (m_controller) { return; } // 如果希望使用固定版本运行时，把第一个参数改成对应路径 // std::wstring runtimePath = L"D:\\MyApp\\WebView2Runtime"; // 这里传 nullptr 表示使用系统 Evergreen Runtime auto options = Microsoft::WRL::Make<CoreWebView2EnvironmentOptions>(); options->put_Language(L"zh-CN"); options->put_AdditionalBrowserArguments(L"--allow-file-access-from-files"); HRESULT hr = CreateCoreWebView2EnvironmentWithOptions( nullptr, // browserExecutableFolder，固定版本时填路径 L"D:\\MyApp\\WebView2UserData", // userDataFolder options.Get(), Microsoft::WRL::Callback<CreateCoreWebView2EnvironmentCompletedHandler>( [this](HRESULT result, ICoreWebView2Environment* env) -> HRESULT { if (FAILED(result) || !env) { AfxMessageBox(L"WebView2 环境创建失败，请检查 Runtime 是否安装"); return S_OK; } m_environment = env; HRESULT hrCreate = env->CreateCoreWebView2Controller( this->GetSafeHwnd(), Microsoft::WRL::Callback<CreateCoreWebView2ControllerCompletedHandler>( [this](HRESULT res, ICoreWebView2Controller* controller) -> HRESULT { if (FAILED(res) || !controller) { AfxMessageBox(L"WebView2 控制器创建失败"); return S_OK; } m_controller = controller; m_controller->get_CoreWebView2(&m_webView); m_webViewReady = true; ResizeWebView(); // 导航之前先设置虚拟主机名映射 ConfigureVirtualHostName(); // 加载本地网页 m_webView->Navigate(L"https://myapp.local/index.html"); return S_OK; }).Get()); return hrCreate; }).Get()); if (FAILED(hr)) { AfxMessageBox(L"WebView2 初始化失败"); } }代码里的ConfigureVirtualHostName是关键一步。直接用file:///协议虽然能打开本地文件，但网页里的 JavaScript 发 fetch 请求或者加载相对资源时经常因为跨域问题被拦截。用虚拟主机名映射，相当于把本地目录变成一个域名入口，浏览器行为更接近真实部署环境。
HRESULT CWebView2HostDlg::ConfigureVirtualHostName() { if (!m_webView) { return E_FAIL; } // 将本地 html 目录映射为 https://myapp.local return m_webView->SetVirtualHostNameToFolderMapping( L"myapp.local", L"D:\\MyApp\\html", COREWEBVIEW2_HOST_RESOURCE_ACCESS_KIND_ALLOW); }注意第二个参数是本地文件夹的完整路径，网页里所有资源的相对路径都会相对于这个文件夹解析。第三个参数是访问权限，ALLOW表示允许浏览器页面访问该虚拟主机名下的资源，如果需要跨域读取，可以用ALLOW_AND_CORS。如果只是展示静态页面，ALLOW就够了，ALLOW_AND_CORS会放宽跨域策略，非必要不建议开。
3.4 调整控件大小和窗口联动
MFC 对话框改变大小时，WebView2 控制器默认不会自动跟着变，需要手动把新窗口大小设置给它。在OnSize里调用ResizeWebView，其中RECT的坐标是相对于宿主窗口客户区的。如果不做这一步，你会看到网页只在最初创建时显示一个固定大小，窗口拉大后周围全是空白，很影响体验。
void CWebView2HostDlg::ResizeWebView() { if (!m_controller) { return; } CRect rcClient; GetClientRect(&rcClient); RECT bounds = { 150, 10, rcClient.right - 10, rcClient.bottom - 10 }; m_controller->put_Bounds(bounds); }我把网页区域放在左侧留出 150 像素，方便放一个功能导航栏或按钮栏。如果你希望 WebView2 铺满整个客户区，直接把bounds设置成rcClient即可。还要注意 DPI 缩放的问题：在高 DPI 显示器上，如果 MFC 进程没有按 DPI 感知进行配置，WebView2 渲染出来的页面会发虚或大小错乱。建议在InitInstance里调用SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)，并且ResizeWebView里使用物理像素进行换算。
3.5 加载本地网页的三种方式总结
本地网页的加载，我整理成三种方式，实际项目按需选择：
| 方式 | 代码写法 | 适用场景 |
|---|---|---|
| file 协议 | Navigate(L"file:///D:/MyApp/html/index.html") | 临时调试，最快最直接 |
| 虚拟主机名映射 | SetVirtualHostNameToFolderMapping+Navigate(L"https://myapp.local/index.html") | 正式项目，资源多、需要 fetch 请求 |
| 嵌入资源 | 把 html 作为资源文件读取后NavigateToString | 单文件小型页面，不想暴露磁盘路径 |
file://协议的完整格式是file:///后面跟盘符和路径，一共三个斜杠，这个地方非常容易写错。虚拟主机名映射最省心，但要注意名称不要跟真实域名冲突，我习惯用应用名缩写 + .local这种命名，比如myapp.local、equipmon.local。
4. 让本地网页和 C++ 对话：双向通信的关键写法
4.1 WebView2 的消息机制概览
网页和原生 C++ 通信是嵌入功能最常见的需求。比如设备管理页面点击一个按钮，需要调用 MFC 里封装的串口或网络接口；或者 C++ 检测到设备状态变化，需要刷新网页上的图表。WebView2 提供了基于 JSON 的消息通道，JavaScript 端通过window.chrome.webview.postMessage(message)把消息发给 C++ 端，C++ 端通过PostWebMessageAsJson把消息发给 JavaScript 端。两边接收消息都有对应的事件回调。
这套机制比传统的window.external+ ActiveX 方式优雅得多，消息内容只要能被JSON.parse解析，就能传结构化数据，不用自己拼字符串。
4.2 C++ 端注册接收 JavaScript 消息
在 WebView2 初始化完成后，注册WebMessageReceived事件。注意TryGetWebMessageAsString返回的字符串需要调用CoTaskMemFree释放，否则会内存泄漏。我在回调里做了简单的 JSON 解析，你可以引入json.hpp或 C++/WinRT 的 JSON 库做更复杂的解析。
// 注册消息接收回调 void CWebView2HostDlg::RegisterWebMessageHandler() { if (!m_webView) { return; } m_webView->add_WebMessageReceived( Microsoft::WRL::Callback<ICoreWebView2WebMessageReceivedEventHandler>( [this](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args) -> HRESULT { LPWSTR message = nullptr; args->TryGetWebMessageAsString(&message); if (message) { CString strMessage(message); CoTaskMemFree(message); // 这里根据消息内容做分发 if (strMessage.Find(L"\"cmd\":\"readDevice\"") != -1) { // 调用 C++ 设备读取函数 SendDeviceStatus(); } else if (strMessage.Find(L"\"cmd\":\"saveConfig\"") != -1) { // 调用 C++ 保存配置函数 } } return S_OK; }).Get(), &m_webMessageToken); }JavaScript 端发送消息只需要一行：
window.chrome.webview.postMessage(JSON.stringify({ cmd: "readDevice", id: 3 }));4.3 C++ 端主动给网页发消息
C++ 端发消息用PostWebMessageAsJson。这个方法要求传入一个 JSON 字符串，网页端监听message事件接收。举个实际例子：设备状态发生变化时，MFC 里的定时器或后台线程会触发，这时把状态 JSON 推给网页，网页实时更新界面。
void CWebView2HostDlg::SendDeviceStatus() { if (!m_webView) { return; } CString strJson = L"{\"type\":\"deviceStatus\",\"online\":true,\"temperature\":36.5}"; m_webView->PostWebMessageAsJson(strJson.GetBuffer()); }网页端监听：
window.chrome.webview.addEventListener('message', event => { const data = JSON.parse(event.data); if (data.type === 'deviceStatus') { document.getElementById('status').textContent = data.online ? '在线' : '离线'; } });这里有一个开发中容易被忽略的问题：如果网页还没加载完成，C++ 端就调用PostWebMessageAsJson，消息会丢失。稳妥的做法是等网页初始化完成后再往页面发消息。你可以选择在NavigationCompleted事件里发一个“初始化状态”给页面，让页面主动来拉取数据，相当于“握手”。
4.4 用事件机制避免线程卡顿
MFC 里如果涉及后台线程调用 WebView2，我建议不要直接在后台线程里操作 COM 对象。因为 WebView2 的接口访问是有线程要求的，很多接口需要在创建它的线程（通常是 UI 线程）上调用。我自己习惯的做法是：后台线程拿到状态后，通过PostMessage给对话框主窗口发送一个自定义消息，在OnDeviceStateChanged里调用PostWebMessageAsJson。这样既避免跨线程调用 COM 接口，也不会因为把耗时逻辑放在 UI 线程导致界面卡顿。
如果你想直接用std::async做异步操作，也请记得在回调里切回 UI 线程再调用 WebView2。
4.5 与同页面内控件的协作技巧
做产品时，经常想在 MFC 界面里放一个 ComboBox 来切换不同的本地页面。这个需求实现起来很简单，只要在OnCbnSelchange事件里根据选中的索引调用Navigate即可。比如 index 0 跳转到dashboard.html，index 1 跳转到help.html。这里要注意的是，如果页面间需要保留状态，建议多创建几个 WebView2 实例而不是一个实例反复导航；如果只是简单的内容切换，一个实例就够。
顺带提一个小细节：MFC 的CButton默认样式比较土，给按钮设置背景色可以通过OnCtlColor重写实现，但注意 WebView2 控件是一种外部渲染窗口，不参与 MFC 的自绘体系，所以按钮颜色改动只影响原生按钮，不会影响网页内部的样式。网页内的外观请完全交给 CSS 控制，这也是嵌入 Web 的优势。
5. 常见报错与排查技巧：把坑提前踩平
5.1 初始化时报“Could not find the WebView2 runtime”
这是出现频率最高的错误，我在内网部署时几乎每次都遇到。先用GetAvailableCoreWebView2BrowserVersionString确认系统是否有可用 Runtime，如果返回空，优先安装离线安装包。安装时要注意架构：x64 程序需要 x64 Runtime，x86 程序需要 x86 Runtime，不能混用。
如果你确认机器上装了 Edge，但仍然报错，还有一个原因是环境变量和部署目录的问题。Evergreen Runtime 在注册表中登记路径，如果被安全软件清理或者系统优化工具误删，也会出现找不到的情况。此时重装一次离线包可以解决。对于 Fixed Version 部署，则要检查传入的browserExecutableFolder路径是否存在，且目录内的msedgewebview2.exe或者WebView2Loader.dll是否完整。
5.2 页面加载后白屏或显示空白
白屏问题有两种常见来源。第一种是虚拟主机名映射后资源路径错误。如果你映射的目录里没有index.html或者文件名大小写不匹配，页面就会显示空白。第二步用开发者工具看一下具体错误，能在DevTools控制台里看到 404 或者跨域报错，定位会快很多。第二种是本地文件协议访问限制。使用file://协议时，部分浏览器特性会被禁用，比如fetch本地文件、访问localStorage，这些在无痕模式下尤其明显。优先切换到虚拟主机名映射。
如果页面本身有 JavaScript 运行异常，C++ 端看不到错误信息，一个实用技巧是在初始化时注册add_WebResourceRequested或者通过DevToolsProtocolEventReceived监听控制台日志。你也可以先在一个独立 Edge 窗口里打开本地页面，确认页面本身没有问题，再回到 MFC 里排查。
5.3 WebView2 尺寸不跟随窗口变化
控件大小不动或错位，几乎都是没有在WM_SIZE消息里调用put_Bounds。有一个细节：WM_SIZE在窗口创建初期也会触发，那时m_controller可能还没初始化，所以回调里要加空指针判断。还有，不要在Compare或者拉伸过程中频繁调用put_Bounds，会导致窗口闪烁。我通常用一个OnSizeEnd的延时处理，用户停止拉伸 200 毫秒后再更新，或者直接每次重绘都更新，但要确保更新逻辑足够轻量。
5.4 程序退出时崩溃或句柄泄漏
WebView2 控制器和环境的生命周期需要手动管理。正确顺序是先释放控制器，再释放环境。在 MFC 对话框的OnDestroy里，建议主动调用：
void CWebView2HostDlg::OnDestroy() { if (m_controller) { m_controller->Close(); m_controller.Reset(); } m_webView.Reset(); m_environment.Reset(); CDialogEx::OnDestroy(); }m_controller->Close()会释放 WebView2 的渲染进程资源。如果不调用，窗口销毁后子进程可能残留，任务管理器里能看到多个msedgewebview2.exe进程，反复开关页面就会积累大量僵尸进程。另外，如果一个对话框被重复打开关闭，注意避免重复初始化 WebView2。我的做法是初始化前先判断m_controller是否为空，为空才创建新环境，否则复用。
5.5 调试技巧：开启 DevTools 协议
WebView2 支持远程调试。只需在CreateCoreWebView2EnvironmentWithOptions的附加参数里加上--remote-debugging-port=9222，然后在 Edge 浏览器中访问http://localhost:9222，就能像调试普通网页一样调试 MFC 内嵌的页面。这个调试方式特别适合排查页面加载错误和网络请求问题。注意，远程调试端口在生产环境不要开放，不然会有安全风险。
我在调试时还会注册NavigationCompleted事件，把最终 URL 和状态码打出来，能快速判断是文件路径问题还是权限问题。代码如下：
m_webView->add_NavigationCompleted( Microsoft::WRL::Callback<ICoreWebView2NavigationCompletedEventHandler>( [this](ICoreWebView2* sender, ICoreWebView2NavigationCompletedEventArgs* args) -> HRESULT { BOOL isSuccess = FALSE; args->get_IsSuccess(&isSuccess); COREWEBVIEW2_WEB_ERROR_STATUS status; args->get_WebErrorStatus(&status); if (!isSuccess) { CString strError; strError.Format(L"页面加载失败，错误码：%d", (int)status); OutputDebugString(strError); } return S_OK; }).Get(), &m_navigationToken);5.6 常见问题速查表
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
| could not find the webview2 runtime | Runtime 未安装或架构不匹配 | 安装离线包，检查 x86/x64 是否对应 |
| 页面白屏 | 映射目录错误、JS 报错、跨域限制 | 用虚拟主机名映射，开 DevTools 看控制台 |
| 网页不随窗口缩放 | 未调用 put_Bounds | 在 WM_SIZE 中更新 Bounds |
| 退出后残留进程 | 未调用 Close 释放控制器 | OnDestroy 里先 Close 再 Reset |
| 页面加载卡顿 | 初始化在 UI 线程执行大量同步逻辑 | 异步回调中做轻量操作，后台数据用消息投递 |
| 中文路径显示异常 | URL 编码问题或路径分隔符错误 | 确保路径使用宽字符串，盘符后是双反斜杠 |
WebView2 总体而言是个让 MFC 程序员找回“现代前端开发”感觉的好东西。我个人的经验是，发现真正的难点不在 API，而在于把异步初始化和 MFC 窗口生命周期理顺。只要把环境创建、控制器创建、消息注册这几步的顺序和线程关系理清楚，后面加页面、加通信，都是水到渠成的事。如果你打算嵌的页面比较多，建议做一层封装，把 WebView2 的初始化、导航、消息收发统一收口，这样后续项目复用起来会很舒服。
另外一个很实用的建议是，把WebView2UserData目录统一放在%LOCALAPPDATA%\YourAppName\WebView2下，不要用临时目录，不然每次启动都要新建用户数据，缓存和本地存储都会失效。我踩过这个坑，页面第一次加载总要 3 到 4 秒，后来才发现是用户数据目录被系统清理了，改成固定路径后加载速度明显提升。如果你也是边学边做，建议直接先跑一个最小 Demo，把本地页面加载出来再逐步加功能，别上来就追求大而全。等你把所有链路都跑通了，就会发现 WebView2 在 MFC 项目里其实是一个很稳定、很省心的组件。
