WebView2 在 WinForms 中崩溃主因是缺失 WebView2 Runtime 或 Edge（≥116），需手动安装或显式指定运行时路径；白屏卡死多因事件订阅顺序错误、线程模型不符或未等 CoreWebView2 初始化完成就调用 API。
WebView2 在 WinForms 里能跑起来，但不装运行时就直接崩溃——不是代码写错了，是环境没配好。
WebView2 初始化失败：CoreWebView2InitializationException 怎么破
这个异常几乎总是因为系统缺 WebView2 Runtime 或 Edge（Chromium 内核）导致的，不是你的 InitializeComponent() 没调对，也不是 NuGet 包版本错。它根本没机会走到 C# 逻辑里，就在 COM 层被拦下了。
- 检查控制面板 → “已安装的程序”，找
Microsoft Edge WebView2 Runtime或Microsoft Edge（版本号 ≥ 116） - 没装？去官网下独立安装包：
https://go.microsoft.com/fwlink/p/?LinkId=2124703，别依赖“自动下载”——EnsureCoreWebView2Async(null)默认只查注册表，而注册表路径可能损坏或指向旧版 - 企业环境或离线部署？直接打包
Microsoft.WebView2.FixedVersionRuntime.*.nupkg，解压后用CoreWebView2Environment.CreateAsync(..., webView2RuntimePath: @"path\to\runtime")显式指定路径 - 错误日志里看到
0x80070002（找不到文件）或WEBVIEW2_ERROR_INVALIDARGUMENT，基本可以锁定是运行时缺失或路径无效
WinForms 中 WebView2 控件不显示、白屏、卡死的常见原因
控件拖进窗体后什么都没出来？不是没写 Navigate()，而是底层消息循环或线程模型没对上。
- 确保窗体在 STA 线程启动：WinForms 默认满足，但如果你从后台线程
new Form1().Show()，就得先Thread.SetApartmentState(ApartmentState.STA) -
CoreWebView2InitializationCompleted事件必须订阅后再调EnsureCoreWebView2Async()，否则事件永远不触发——很多人把顺序写反了 - 别在
Form_Load里直接Navigate()；等CoreWebView2InitializationCompleted回调里再调，否则CoreWebView2还是null - 窗体
Resize时如果手动改Size又没处理好 Dock，可能触发重绘死锁；推荐直接设webView21.Dock = DockStyle.Fill，省事且稳定
怎么拿到渲染完成后的最终 HTML（含 JS 动态内容）
想抓 Vue/React 页面的真实 DOM？别用 DocumentText——那是初始 HTML，JS 还没跑。得等页面“活”了，再执行 JS 提取 document.documentElement.outerHTML。
- 监听
CoreWebView2.NavigationCompleted事件，确认e.IsSuccess == true且e.WebErrorStatus == CoreWebView2WebErrorStatus.None - 用
ExecuteScriptAsync("document.documentElement.outerHTML")，不是document.body.innerHTML——前者包含和所有注入的 script/style - 如果页面有防爬 JS（比如检测
document.hidden），加一行await CoreWebView2.ExecuteScriptAsync("document.hidden = false;")欺骗一下 - 返回值是 JSON 字符串，需用
JsonSerializer.Deserialize<string>(result)解包，别直接当字符串用
缓存、登录态、开发者工具这些实用配置怎么开
默认行为不适合生产场景：每次重启都重新登录、没法调试、JS 报错看不见。
- 用户数据目录必须显式指定，否则缓存和 Cookie 会丢：
CoreWebView2Environment.CreateAsync(userDataFolder: Path.Combine(Path.GetTempPath(), "MyAppWebView2")) - 开启 DevTools：
CoreWebView2.Settings.AreDevToolsEnabled = true，右键网页就能唤出；但发布前记得关掉，避免用户误操作 - 禁用图片加载节省带宽（比如做 HTML 抓取时）：
CoreWebView2.Settings.IsImageLoadingEnabled = false - 需要拦截请求或注入脚本？用
CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("...")，比 onload 更早生效
最常被忽略的一点：WebView2 不是“控件初始化完就能用”，它分三层——环境（Environment）、控制器（Controller）、核心（CoreWebView2）。很多问题出在你只等了第一层，却在第二层还没 ready 的时候就调用了第三层 API。盯住 CoreWebView2InitializationCompleted 和 NavigationCompleted 这两个事件，别跳步。
