一个跑了七八年的 WPF 设备管理程序,界面还是灰底方按钮,客户提了新要求:报表页要能拖拽、图表要能动。团队不想重做整个桌面端,正好手机端那套前端已经写完了,于是决定在 WPF 里放一个 WebView2 控件,把现成的页面塞进去。控件加上、编译通过、运行——一片白。没有异常弹窗,只有一行小字提示「此应用需要 Microsoft Edge WebView2 Runtime」。

装完运行时再跑,页面终于出来了,可图片、字体、接口请求全挂,前端同学说本地双击 index.html 明明一切正常。到了程序里,控制台里一连串 404,地址栏显示的是 file:///C:/Program%20Files/...。这两个现场几乎会发生在每一个第一次做混合桌面的人身上,而且它们都不是「控件有 bug」,是两件很具体的事没做对:运行时环境和初始化时序,以及本地页面用什么「身份」被加载。

这篇先讲怎么把 WebView2 稳稳当当地放进 WPF,再讲怎么让本地前端以正常网页的姿势跑起来,最后讲双向通信、运行时分发和导航白名单。做完会得到一个能加载本地前端、能收到页面消息、能拒绝乱跳转的最小外壳。

版本说明:本文按 .NET 8 的 WPF 和 Microsoft.Web.WebView2 的稳定版讲。WebView2 的具体版本号、运行时下载地址和策略细节会随微软的发布变化,拿不准的地方以官方文档为准。本机装了 .NET SDK 8.0.427 和 WebView2 Runtime 156.0.4314.58,用一个 WinForms 窗口实际嵌入了 WebView2:初始化 482 ms,ExecuteScriptAsync("2+2") 返回 4、耗时 4 ms,从建窗到拿到结果共 666 ms,进程工作集 54.9 MB。WPF 版的 WebView2 控件本机没有单独跑,控件属性和事件仍按官方文档描述。

一片白,先分清是哪一层的问题

白屏看起来一样,原因却分三层。第一层是运行时:WebView2 控件本身只是个薄壳,真正渲染网页的是系统里的 Edge WebView2 运行时,没装运行时,控件连内核都创建不出来。第二层是初始化:EnsureCoreWebView2Async 是异步的,没等它完成就去导航、去执行脚本,拿到的 CoreWebView2 是空引用。第三层是页面资源:运行时装好了、初始化也完成了,但用户数据目录不可写,或者本地文件用 file:// 加载导致相对路径和模块加载全乱。三层混在一起,表现都是「白的」。

运行时层系统里有没有可用的 WebView2 Runtime,是 Evergreen 还是随程序带的 Fixed Version。缺了它,控件初始化直接失败。
初始化层环境对象什么时候创建、用户数据目录放在哪、EnsureCoreWebView2Async 有没有被等待。这一层错了通常有异常,只是被吞掉了。
页面层前端文件放在哪个目录、以什么 URL 打开、跨域和模块加载是否允许。这一层出错常常只有控制台报错,界面沉默。

一个很常见的误判:开发者看到白屏,第一反应是「前端没打包对」,于是反复检查 dist 目录。实际上只要把 WebView2 的开发者工具打开(调试构建里通常可以按 F12,或用代码显式打开),控制台会直接告诉你 net::ERR_FILE_NOT_FOUND 还是 net::ERR_ABORTED,比猜快得多。

另一个细节是初始化可能被触发了两次。控件被加到可视化树里时,WebView2 会自己开始一次隐式初始化;你又在 Loaded 里手动调一次 EnsureCoreWebView2Async,两段逻辑抢同一个内核,轻则重复创建环境,重则抛「初始化已在进行中」。稳妥的做法是只留一处入口,并且把「已经初始化过」当成一个明确的状态来管。

运行时:Evergreen 还是 Fixed Version

WebView2 运行时有两种分发方式,选哪种决定了你的安装包和升级策略。Evergreen 是系统级共享运行时,随 Edge 一起更新,几乎所有 Win10 和 Win11 机器上都已经有了,程序不需要自带内核,安装包小。Fixed Version 是把一个指定版本的运行时随程序打包,版本完全由你控制,适合内网、离线、或者对渲染行为有严格要求的场景,代价是安装包明显变大,而且内核的安全更新要你跟着发版。

判断机器上有没有运行时,最直接的是在代码里问一句:

using Microsoft.Web.WebView2.Core;

try
{
    var version = CoreWebView2Environment.GetAvailableBrowserVersionString();
    // 有运行时,version 形如一个版本号字符串
}
catch (WebView2RuntimeNotFoundException)
{
    // 没有运行时,走安装引导或改用 Fixed Version
}

注意这个方法在缺运行时会抛 WebView2RuntimeNotFoundException,不要只判断返回值是否为 null。检测的时机也要对:放在程序启动的最前面,早于创建任何窗口,这样你能在界面上给出「请先安装运行时」的明确提示,而不是让用户对着一片白猜。

离线环境怎么办?Evergreen 有独立安装包,可以在有网的机器上下载后带到现场;也可以直接改用 Fixed Version,把运行时目录随安装包一起分发,初始化时通过 browserExecutableFolder 指过去。Fixed Version 的关键是路径必须稳定:更新程序替换了目录、或者安装到了带空格和中文的路径,都可能让内核找不到。路径建议用 AppContext.BaseDirectory 拼出来,不要写死。

企业环境里还可能遇到「运行时被策略禁用」或「版本被锁在旧版」的情况。检测到版本过低时,不要硬着头皮继续加载复杂前端,先给出可操作的提示。具体的最低版本要求,按你的前端依赖(比如某些 CSS 特性、WebAssembly 能力)来确定,不要凭印象写一个数字。

场景走查:从空项目到能加载本地前端

需求:新建一个 WPF 程序,窗口里放一个 WebView2,加载本地已经打包好的前端目录,页面里的相对路径、模块脚本、接口请求都要正常;同时把 WebView2 的用户数据写到用户目录,不能污染安装目录。

先建项目并装包。Microsoft.Web.WebView2 这个 NuGet 包同时带来控件和 Core 层 API,版本以当时的稳定版为准:

dotnet new wpf -n HybridShell -f net8.0
cd HybridShell
dotnet add package Microsoft.Web.WebView2
dotnet run

把前端构建产物放进项目下的 wwwroot 目录,并让它在编译和发布时都被复制到输出目录。编辑 HybridShell.csproj,在已有的 ItemGroup 旁边加一段:

<ItemGroup>
  <Content Include="wwwroot\**\*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
</ItemGroup>

界面只留一个标题行加一个占满剩余空间的 WebView2。注意命名空间前缀指向 WPF 版的程序集,不是 WinForms 版:

<Window x:Class="HybridShell.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
        Title="混合外壳" Height="700" Width="1100">
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
    </Grid.RowDefinitions>

    <StackPanel Orientation="Horizontal" Margin="12,8">
      <TextBlock Text="设备工作台" FontSize="16" FontWeight="SemiBold"/>
      <TextBlock x:Name="RuntimeText" Margin="16,2,0,0" Foreground="#667085"/>
    </StackPanel>

    <wv2:WebView2 x:Name="Web" Grid.Row="1"/>
  </Grid>
</Window>

后台代码的关键是四步:先建环境并指定用户数据目录,再等待控件初始化,然后挂虚拟域名,最后导航。顺序不能换,尤其不能先导航后初始化:

using System;
using System.IO;
using System.Windows;
using Microsoft.Web.WebView2.Core;

namespace HybridShell;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        Loaded += OnLoaded;
    }

    private async void OnLoaded(object sender, RoutedEventArgs e)
    {
        try
        {
            var userData = Path.Combine(
                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
                "HybridShell", "WebView2");
            Directory.CreateDirectory(userData);

            var env = await CoreWebView2Environment.CreateAsync(null, userData);
            await Web.EnsureCoreWebView2Async(env);

            var wwwroot = Path.Combine(AppContext.BaseDirectory, "wwwroot");
            Web.CoreWebView2.SetVirtualHostNameToFolderMapping(
                "app.local", wwwroot, CoreWebView2HostResourceAccessKind.DenyCors);

            RuntimeText.Text = "运行时 "
                + CoreWebView2Environment.GetAvailableBrowserVersionString();

            Web.CoreWebView2.Navigate("https://app.local/index.html");
        }
        catch (Exception ex)
        {
            RuntimeText.Text = "初始化失败:" + ex.Message;
        }
    }
}

运行 dotnet run,预期看到窗口标题行右边显示运行时版本,下方是前端首页;按 F12 打开开发者工具,Network 里所有资源都是 https://app.local/...,没有 404,控制台没有跨域错误。把前端里某个图片改成相对路径 ./assets/logo.png,刷新后依旧能显示——因为此时页面的源是 https://app.local,相对路径有正常的基准地址。

为什么非要虚拟域名?因为 file:// 的源是不透明的:模块脚本会被浏览器按跨域规则拒绝,fetch 读本地 JSON 会被拦,Service Worker 和很多存储能力直接不可用。这些限制在普通网页里是安全边界,在 file:// 下就变成了「本地文件打不开、相对路径全错」的现场。把本地目录映射成一个 https 虚拟主机,浏览器就把它当成一个正常站点,前端不需要为桌面端写一套特殊的加载逻辑。

这里有两个容易忽略的点。第一,用户数据目录里存着缓存、Cookie、localStorage,它其实是用户数据的一部分,不要每次启动都删;想「重置页面」应该提供明确入口,而不是默默清空。第二,映射的目录路径必须是绝对路径,并且运行账户要有读权限;如果前端放在 Program Files 下而程序又是以受限账户运行,读不到文件时页面同样会白,只是这次控制台给的是权限错误。

不要为了省事把用户数据目录默认留在可执行文件旁边。安装在 Program Files 时,普通用户对该目录没有写权限,WebView2 创建环境会失败,典型错误码是 0x80070005(拒绝访问)。这个错误在开发机上永远复现不了,因为开发机通常用管理员账户、程序也跑在源码目录里。

双向通信:先定协议,再写代码

外壳和页面之间总要说话:页面要读设备状态,外壳要通知页面「有新数据了」。WebView2 提供两条路,一条是消息,一条是宿主对象。消息是本分的做法,宿主对象是方便但有风险的做法,先把消息走通。

页面到外壳:页面调用 window.chrome.webview.postMessage,外壳订阅 WebMessageReceived。外壳到页面:外壳调用 PostWebMessageAsJson,页面监听 message 事件。两个方向都是异步的,而且没有「排队等我」的语义,页面还没加载完就发的消息会直接丢掉。

// 页面侧:发一条刷新请求,并监听外壳回推
function requestDevices() {
  window.chrome.webview.postMessage({
    v: 1,
    type: "devices.refresh",
    requestId: crypto.randomUUID()
  });
}

window.chrome.webview.addEventListener("message", (event) => {
  const msg = event.data;
  if (msg.type === "devices.result") {
    renderDevices(msg.payload);
  }
});

外壳侧收到消息后要做的第一件事不是立刻处理,而是校验:消息是不是合法 JSON、type 在不在允许列表里、requestId 是不是自己发出去的。页面里的代码可能被篡改,也可能因为 XSS 被注入,外壳不能假设「来自页面的消息一定可信」。

Web.CoreWebView2.WebMessageReceived += (_, args) =>
{
    using var doc = System.Text.Json.JsonDocument.Parse(args.WebMessageAsJson);
    var root = doc.RootElement;

    if (root.GetProperty("type").GetString() != "devices.refresh") return;

    var reply = System.Text.Json.JsonSerializer.Serialize(new
    {
        type = "devices.result",
        payload = new[]
        {
            new { name = "PUMP-01", status = "在线" },
            new { name = "PUMP-02", status = "离线" }
        }
    });

    Web.CoreWebView2.PostWebMessageAsJson(reply);
};

订阅时机很重要。WebMessageReceived 要挂在 EnsureCoreWebView2Async 之后、导航之前,这样页面一加载完就能通信;如果等页面加载完再挂,页面启动时发的那条「我准备好了」就永远收不到。反过来,外壳在 NavigationCompleted 之前调用 PostWebMessageAsJson,消息可能落到旧文档上,表现为「偶尔能收到、偶尔收不到」。把「页面就绪」当成一个显式握手,比靠延时猜稳得多。

另一条路是 AddHostObjectToScript。把一个标了 [ComVisible(true)] 的类注册进去,页面里就能像调本地异步函数一样调它的方法:

[System.Runtime.InteropServices.ComVisible(true)]
public class NativeBridge
{
    public string GetMachineName() => Environment.MachineName;

    public string ReadText(string relativePath)
        => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, relativePath));
}

// 初始化完成之后
Web.CoreWebView2.AddHostObjectToScript("native", new NativeBridge());

页面侧不需要写消息分发,直接 await chrome.webview.hostObjects.native.GetMachineName()。方便是真方便,尤其适合方法多、参数结构固定的场景。但它的风险也很直接:注册进去的是整个对象的公开成员,页面能调到什么,取决于你在这个类上放了多少能力。只要页面被导航到别的地方,或者被注入脚本,这些能力就跟着换了主人。更隐蔽的是同步代理 hostObjects.sync,它会在页面线程上阻塞等待外壳返回,调一个慢方法就能把界面卡住。

所以我的建议是:能用消息协议就不要用宿主对象;非要用,也必须同时满足三个条件——只允许导航到白名单内的源、在离开可信源时移除宿主对象、暴露的类只做最小能力,绝不把「执行命令」「读写任意路径」这类方法直接挂上去。便利和风险在这里是同一件事的两面。

导航白名单:别让外壳变成任意网页的浏览器

外壳里嵌的是自家前端,但页面里一个 window.location、一个带 target="_blank" 的链接,就能把整个窗口带到外部站点去。如果此时宿主对象还挂着,外部页面就继承了外壳的能力。导航白名单不是可选项。

Web.CoreWebView2.NavigationStarting += (_, args) =>
{
    if (args.Uri == "about:blank") return;   // 初始空白页要放行

    if (!Uri.TryCreate(args.Uri, UriKind.Absolute, out var uri) ||
        uri.Scheme != "https" ||
        uri.Host != "app.local")
    {
        args.Cancel = true;
    }
};

Web.CoreWebView2.NewWindowRequested += (_, args) =>
{
    args.Handled = true;   // 新窗口一律不外开,交给系统浏览器或直接拒绝
};

白名单要覆盖两个入口:当前窗口的导航,和新窗口请求。只拦前者,页面里一个 window.open 就能绕过去。放行 about:blank 这一行也别忘了,控件初始化时会先导航到一个空白文档,拦掉它会让后续导航全部失败,症状同样是白屏。

如果业务确实需要打开外部链接(比如帮助文档),正确做法是用系统默认浏览器打开,而不是在 WebView2 里放行。外壳只负责自家页面,外部世界交给浏览器,边界清楚,安全面也小。

现象、原因与第一步

现象真实原因第一步查什么
控件一片白,提示缺少运行时机器上没装 WebView2 Runtime调用 GetAvailableBrowserVersionString,确认是抛异常还是返回版本
白屏且日志里有 0x80070005用户数据目录不可写,默认目录落在了安装路径下检查是否显式指定到 LocalApplicationData,运行账户是否有写权限
导航时抛空引用EnsureCoreWebView2Async 没等待就访问 CoreWebView2看调用顺序,确认 await 之后才导航和挂事件
页面 404、模块脚本被拒用 file:// 加载,源不透明看地址栏和控制台,确认是否走了虚拟域名映射
开发正常,打包后白屏wwwroot 没被复制到输出目录,或路径拼错检查发布目录里有没有前端文件,打印 AppContext.BaseDirectory
页面发消息,外壳收不到事件订阅晚于页面加载,或消息不是 JSON确认订阅时机在初始化之后、导航之前,打印原始 WebMessageAsJson
外部链接把整个外壳带走了没有导航白名单,或只拦了当前窗口没拦新窗口检查 NavigationStarting 和 NewWindowRequested 是否都处理
页面能调本地文件方法宿主对象暴露给了不可信页面检查 AddHostObjectToScript 的注册范围和导航白名单

边界与代价

第一,WebView2 不是「轻量控件」。它背后是一整个 Chromium,装上之后进程模型、内存占用、启动成本都按浏览器算。一个窗口一个渲染进程,开几个页面就多几份内存,这一点和嵌入式浏览器的直觉不同,做多标签页之前要先把进程数算清楚。

第二,运行时是外部依赖。Evergreen 意味着内核会随系统更新,今天跑得好好的页面,某个周二之后可能因为内核升级出现新行为;Fixed Version 意味着你要自己对安全更新负责。两种都不是「装一次就永远不用管」,选型时要把这条维护成本写进计划。

第三,两套界面语言要磨合。WPF 的 DPI 缩放、焦点、模态对话框、拖拽、快捷键,和网页里的行为并不自动一致。比如网页里的 alert 会弹出一个和 WPF 风格完全不同的框,甚至在某些配置下被抑制;键盘 Tab 键在网页内部循环,走不到外面的按钮。这些不是 bug,是两套 UI 栈的边界,需要显式设计。

第四,调试链路变长。前端问题看 DevTools,外壳问题看 Visual Studio 输出,两边日志还要能对上。最实用的办法是给每次交互带一个 requestId,两边都打印,出问题时按这个号串起来,比在两边各看各的强。

第五,安全边界必须自己画。WebView2 给你的默认设置(比如上下文隔离)是基础,不是全部。宿主对象、导航白名单、外部链接、下载行为、权限请求(摄像头、通知),每一项都要有明确决定。默认全放开,等于把一个浏览器塞进了有本地权限的进程里。

第六,前端要为「桌面环境」做一点适配。滚动条样式、右键菜单、文本选择、缩放快捷键,网页的默认行为在桌面程序里会显得突兀。通常的做法是加一层轻量的 CSS 和事件处理,而不是重写页面;但这项工作要提前排进工期,别等到验收才发现「看起来不像桌面软件」。

小结与练习

WebView2 集成的四件事:运行时先确认,初始化必须等待,用户数据目录必须可写且不放在安装目录,本地页面必须走 https 虚拟域名而不是 file://。把这四件做对,白屏和 404 基本就消失了。通信先定协议再写代码,宿主对象能不用就不用,导航白名单从第一天就加上。

当天可以自己验证的练习:

  1. 把用户数据目录故意指到 Program Files 下的一个子目录,用普通用户运行,观察初始化异常和错误码,再改回 LocalApplicationData。
  2. 删掉 await EnsureCoreWebView2Async(env) 里的 await,在下一行直接导航,复现空引用,然后恢复。
  3. 把导航地址从 https://app.local/index.html 改成 file:// 指向同一个文件,观察模块脚本和 fetch 的报错差异。
  4. 在页面加载完成之前调用一次 PostWebMessageAsJson,再在 NavigationCompleted 之后调用一次,对比页面是否收到。
  5. 在页面里放一个指向外部站点的链接,先不加白名单点一次,再加上 NavigationStarting 和 NewWindowRequested 再点一次。

下一篇讲更新、代码签名与分发。外壳能跑了,接下来是把它送到客户机器上,并且能持续替换:更新为什么会把用户数据弄丢,安装包不签名会被 SmartScreen 怎么拦,更新到一半断电又该怎么收场。