一个跑了七八年的 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:// 加载导致相对路径和模块加载全乱。三层混在一起,表现都是「白的」。
EnsureCoreWebView2Async 有没有被等待。这一层错了通常有异常,只是被吞掉了。一个很常见的误判:开发者看到白屏,第一反应是「前端没打包对」,于是反复检查 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 拼出来,不要写死。
场景走查:从空项目到能加载本地前端
需求:新建一个 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 基本就消失了。通信先定协议再写代码,宿主对象能不用就不用,导航白名单从第一天就加上。
当天可以自己验证的练习:
- 把用户数据目录故意指到
Program Files下的一个子目录,用普通用户运行,观察初始化异常和错误码,再改回LocalApplicationData。 - 删掉
await EnsureCoreWebView2Async(env)里的await,在下一行直接导航,复现空引用,然后恢复。 - 把导航地址从
https://app.local/index.html改成file://指向同一个文件,观察模块脚本和fetch的报错差异。 - 在页面加载完成之前调用一次
PostWebMessageAsJson,再在NavigationCompleted之后调用一次,对比页面是否收到。 - 在页面里放一个指向外部站点的链接,先不加白名单点一次,再加上
NavigationStarting和NewWindowRequested再点一次。
下一篇讲更新、代码签名与分发。外壳能跑了,接下来是把它送到客户机器上,并且能持续替换:更新为什么会把用户数据弄丢,安装包不签名会被 SmartScreen 怎么拦,更新到一半断电又该怎么收场。