webview2初始化需在sta线程调用coinitializeex；corewebview2异步加载需检查环境并指定运行时路径；消息循环阻塞会导致无响应；回调中须确保对象生命周期安全且避免死锁。
WebView2 初始化失败：CoInitialize 未调用或线程模型不匹配
WebView2 必须在 COINIT_APARTMENTTHREADED 模型的线程上初始化，否则 CreateCoreWebView2Controller 会返回 E_FAIL 或卡死。常见现象是窗口空白、回调不触发、或者日志里出现 0x80070005（访问被拒绝）——实际是 COM 初始化缺失导致的权限误报。
- 主线程启动前必须调用
CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED)；用CoUninitialize()配对释放 - 如果用 Win32
DialogBox或子线程创建 WebView2，得确保该线程也做了相同初始化，不能复用主线程的 COM 环境 - Qt 或 WPF 容器里嵌入时，需确认消息循环线程是否满足 STA 要求；MFC 默认满足，但自定义线程需手动处理
获取 CoreWebView2 失败：环境未安装或版本太旧
CreateCoreWebView2Controller 成功不代表 CoreWebView2 就绪，它异步加载内核。若用户没装 Edge（或仅装了旧版），Environment::CreateAsync 会失败，错误码常为 WEBVIEW2_ERROR_INVALIDARGUMENT 或 0x80070002（找不到文件）。
- 必须显式传入
WebView2RuntimePath（如L"C:\Program Files\Microsoft\Edge\Application"）才能绕过系统自动查找逻辑，避免因注册表路径错乱导致失败 - 调试时打开
WebView2APITrace日志（设置环境变量WEBVIEW2_TRACE_LOGGING=1），能直接看到内核加载路径和失败原因 - 不建议依赖默认系统安装路径；打包时可随应用附带 WebView2 Runtime（
Microsoft.WebView2.FixedVersionRuntime.124.0.2476.0.nupkg），解压后指定其目录
消息循环阻塞导致 WebView2 无响应
WebView2 内部依赖 Windows 消息泵（GetMessage/DispatchMessage）驱动渲染和 JS 回调。如果主线程长时间执行 CPU 密集任务（比如大数组排序、文件读取），UI 会卡住，JS setTimeout、网络请求完成回调、甚至鼠标悬停动画都会停滞。
- 绝对不要在 UI 线程做耗时操作；用
CreateThread+PostMessage把结果发回主线程更新 WebView2 - 启用
WebView2的IsScriptEnabled和AreDefaultScriptDialogsEnabled前，先确认CoreWebView2已就绪（检查m_webView->get_CoreWebView2(&webview2)是否非空） - 监听
WebMessageReceived事件时，回调函数内别做阻塞操作；JS 发来的消息应尽快解析并投递到工作线程处理
C++ 对象生命周期与 WebView2 回调绑定
WebView2 的所有回调（如 ICoreWebView2CreateCoreWebView2ControllerCompletedHandler）都是裸函数指针或 COM 接口，不持有 C++ 对象引用。如果回调里访问已析构的 this，程序大概率崩溃，且堆栈难以定位。
- 用
std::shared_ptr管理宿主类，所有回调用 lambda 捕获shared_from_this()，确保对象存活 - 在窗口销毁时，必须显式调用
m_webView->Close()并置空成员指针；否则 WebView2 可能在后台继续尝试调用已释放对象的虚函数 - 不要在
ICoreWebView2WebMessageReceivedEventHandler回调里直接调用PostMessage向 HWND 发送自定义消息——WebView2 可能还在内部锁中，容易死锁；改用CoreApplication::MainView.CoreWindow.Dispatcher.RunAsync（UWP）或标准线程消息队列
WebView2 的 C++ API 表面简单，但 COM 生命周期、线程模型、异步时机这三点交织在一起，任一环节松动都会导致不可预测的挂起或崩溃。最稳妥的做法是：每个回调入口加 if (!m_webView) return; 防御，所有跨线程交互走消息队列，运行时始终开着 trace 日志观察内核加载链路。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
