WebView2控件不显示网页的主因是未安装独立运行时、初始化时机错误或file://协议受限；需安装Edge WebView2运行时、在Form.Load中await EnsureCoreWebView2Async、用绝对file:///路径加载本地HTML，并确保JS通信使用window.chrome.webview.postMessage。
WebView2 控件没显示网页，可能根本没装运行时
WebView2 不是 .NET 自带组件，它依赖独立的 Edge WebView2 运行时。哪怕你装了最新版 Edge 浏览器，也不代表系统已安装 WebView2 运行时——尤其是客户机或无网环境。
常见错误现象：System.DllNotFoundException: Unable to load DLL 'WebView2Loader.dll' 或控件区域一片灰白、完全不渲染。
- 开发机建议直接下载 Evergreen Bootstrapper 安装，它会自动部署到
%LOCALAPPDATA%\Microsoft\EdgeWebView - 发布应用时，要么打包
WebView2RuntimeInstaller.exe引导用户安装，要么在项目中启用“固定运行时”模式（需手动指定Microsoft.Web.WebView2.FixedVersionRuntime.124.0.2471.64类似路径） - 检查是否启用网络权限：WinForm 默认禁用 Web 请求，需在项目属性 → “安全性” → 勾选“启用 ClickOnce 安全设置”或改用完整信任（调试阶段可临时设为“完全信任”）
InitializeAsync() 必须 await，且不能在构造函数里调用
WebView2 初始化是异步过程，必须等 CoreWebView2InitializationCompleted 事件触发后才能安全调用 Navigate()、ExecuteScriptAsync() 等方法。在未初始化完成前操作，会抛出 System.NullReferenceException: Object reference not set to instance of an object，因为 CoreWebView2 还是 null。
- 不要在窗体构造函数或
Load事件开头直接写await webView21.EnsureCoreWebView2Async(null)—— WinForm 的 UI 线程不允许在构造中 await - 正确做法是在
Form.Load事件中调用，并用 async void（仅此处可接受）或拆成两步：先注册CoreWebView2InitializationCompleted事件，再在事件处理中导航 - 示例片段：
private async void Form1_Load(object sender, EventArgs e) { await webView21.EnsureCoreWebView2Async(null); webView21.Navigate("https://example.com"); }
本地 HTML 文件打不开？路径和权限是关键
用 Navigate("file:///C:/app/index.html") 加载本地文件时，大概率失败——不是路径错，而是 WebView2 默认禁止 file:// 协议跨目录访问，且对相对路径解析极不友好。
- 绝对路径必须用三斜杠：
file:///C:/app/index.html，少一个/就变file:/C:/...，被识别为无效 URI - 更稳妥的做法是用
Environment.CurrentDirectory拼接，并转成完整 file URI：var path = Path.Combine(Environment.CurrentDirectory, "index.html"); webView21.Navigate(new Uri(path).AbsoluteUri);
- 若 HTML 引用了 JS/CSS 子资源，确保它们与 HTML 在同一目录或子目录；WebView2 对
file://的同源策略比浏览器更严格，跨文件夹引用会 404 - 调试时可在
CoreWebView2.WebMessageReceived中监听控制台报错，或启用开发者工具：webView21.CoreWebView2.OpenDevToolsWindow()
JS 与 C# 通信时，window.chrome.webview.postMessage() 发不出去
WebView2 的 JS ↔ C# 双向通信依赖 WebMessageReceived 和 PostWebMessageAsString()，但 JS 端必须用 window.chrome.webview.postMessage()，写成 window.webkit.messageHandlers 或 external.invoke 都无效。
- C# 端注册监听必须在
CoreWebView2初始化完成后：webView21.CoreWebView2.WebMessageReceived += (s, e) => { var msg = JsonSerializer.Deserialize<string>(e.TryGetWebMessageAsString()); // 处理消息 }; - JS 端发送前，务必确认
window.chrome.webview已就绪（它异步注入），推荐加一层检测：if (window.chrome?.webview) { window.chrome.webview.postMessage("hello from js"); } else { console.warn("WebView2 API not ready"); } - 注意：
postMessage()只支持字符串（JSON 序列化后），不支持二进制或函数；大消息可能被截断，单次建议控制在 1MB 内
WebView2 的坑不在 API 多难，而在于初始化时机、运行时依赖、协议限制这三处——漏掉任意一个，页面就静默失败，连错误提示都不给。尤其上线前务必在干净虚拟机里测一遍安装流程和本地文件加载。
