WPF应用WebView2 EnsureCoreWebView2Async永久挂起无法加载HTML

常见挂起触发原因与修复方式 #

• 运行时环境初始化路径异常
  WebView2初始化时默认会在系统本地路径创建用户数据目录，如果该目录存在权限不足、被占用、路径长度超限的问题，初始化流程会静默卡住，无任何异常抛出。
  修复方式：调用初始化方法前，显式创建自定义环境实例，指定有读写权限的临时用户数据路径，示例代码：

  using Microsoft.Web.WebView2.Core;
  
  // 在初始化方法中替换默认的无参Ensure调用
  var env = await CoreWebView2Environment.CreateAsync(
      browserExecutableFolder: null,
      userDataFolder: Path.Combine(Path.GetTempPath(), $"WebView2_{Guid.NewGuid():N}")
  );
  await WpfBrowser.EnsureCoreWebView2Async(env);
  

• 调用时序不匹配
  手动调用EnsureCoreWebView2Async时，如果WebView2控件尚未完成窗口句柄创建（也就是所属窗口还没加载完成、没挂载到UI视觉树），初始化流程会等待控件句柄就绪的信号，最终造成永久挂起。
  复现代码中存在这个典型问题：在按钮事件中创建新的WebWindow对象后，没有先调用窗口的Show()方法触发UI加载，就直接await初始化方法，此时WebView2控件的句柄还未生成，方法自然不会返回。
  修复方式：调整调用时序，先展示承载WebView2的窗口，等控件完成初始化加载后再执行手动初始化逻辑，修正后的按钮事件代码参考：

  private async void OpenHtml_Click(object sender, RoutedEventArgs e)
  {
      var browserWindow = new WebWindow();
      // 先展示窗口，触发控件句柄创建
      browserWindow.Show();
      // 等待初始化完成
      await browserWindow.Initialize();
      browserWindow.LoadHtml(@"<html><head><title>Test title</title></head><body><p>Test</p></body></html>");
  }
  

• 外部程序拦截消息循环
  杀毒软件实时防护、全局窗口消息钩子、第三方UI框架的消息拦截组件，如果阻断了WebView2初始化过程需要的Windows系统消息传递，也会导致初始化静默挂起。可以在最小复现项目中临时关闭安全软件、移除全局钩子，排查是否为该类原因导致。

补充说明 #

观察到的“直接给Source属性传URL可以正常加载”的现象，是因为WebView2控件在检测到Source属性赋值时，会自动和自身的UI加载流程绑定触发隐式初始化，不存在提前等待句柄的问题；而手动提前调用EnsureCoreWebView2Async时，因为没有和UI加载流程绑定，就会卡在等待控件就绪的环节。

内容的提问来源于stack exchange，提问作者Daniele Armanasco