.NET MAUI WebView无法加载本地HTML文件显示空白如何解决

第一步：先确认文件配置没出错 #

• 确保editor.html放在项目的Resources/Raw目录下
• 右键文件打开属性面板，生成操作选MauiAsset，复制到输出目录选「如果较新则复制」
• 不要把生成操作改成EmbeddedResource，会直接导致MauiAsset部署规则失效，文件根本不会被输出到运行目录

第二步：替换错误的Source写法 #

直接在XAML里写Source="editor.html"无法正常加载，XAML不会自动解析MauiAsset的实际运行路径，自然找不到文件。
直接在页面后台写加载逻辑，Windows和Mac Catalyst通用，无需写平台分支判断，可以在页面构造函数的InitializeComponent()方法后添加，也可以重写OnHandlerChanged方法添加：

var assetRoot = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Resources/Raw/");
var htmlPath = Path.Combine(assetRoot, "editor.html");

// 调试阶段可以加校验，快速排查文件有没有被正确部署
if (!File.Exists(htmlPath))
{
    throw new Exception($"本地文件未找到，路径为{htmlPath}，请检查生成操作配置");
}

WebViewQuestionText.Source = new UrlWebViewSource
{
    Url = htmlPath,
    BaseUrl = assetRoot
};

第三步：修复内嵌HTML点链接跳空白的问题 #

之前内嵌HtmlWebViewSource时点击链接跳空白，核心原因是没有给BaseUrl赋值，WebView不知道相对路径要从哪个目录查找文件，自然会跳转到空白页。
正确写法如下：

var assetRoot = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Resources/Raw/");
WebViewQuestionText.Source = new HtmlWebViewSource
{
    Html = @"
<html>
<head></head>
<body>
<h1>.NET MAUI</h1>
<p>本地CSS、图片、链接都能正常加载</p>
<p><a href=""editor.html"">跳转到测试页</a></p>
</body>
</html>",
    // 这行必须加，所有相对路径都会从这个目录查找对应文件
    BaseUrl = assetRoot
};

踩坑提醒 #

• 直接在XAML写Source="editor.html"时，WebView会默认从应用进程的启动根目录找文件，而MauiAsset默认会被部署到Resources/Raw子目录下，路径不匹配自然加载失败
• 拼接路径一律用Path.Combine，不要手动写斜杠，Windows路径分隔符为\、Mac为/，手动拼接很容易出现跨平台兼容问题
• 测试阶段文件名、路径全部使用英文，不要加中文、空格、特殊符号，避免路径编码解析出错
• 公网URL能正常加载说明WebView控件本身功能正常，空白问题100%是本地路径匹配错误导致，无需怀疑控件本身能力
• 不要写死平台绝对路径，应用安装路径在不同发布模式、不同系统版本下都会变化，用AppDomain.CurrentDomain.BaseDirectory拼接路径是目前跨Win/Mac最稳定的方案

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