MAUI Blazor Hybrid完整指南2026：跨端发布

为什么2026年你应该认真考虑Blazor Hybrid？

做跨平台开发的同学，应该都面临过一个经典选择题：要原生性能，还是要开发效率？XAML写原生控件性能确实好，但学习曲线陡峭，UI复用到Web端基本不可能。纯Web方案开发快、组件丰富，可一旦要访问设备API或者离线运行就捉襟见肘了。

Blazor Hybrid就是微软给出的答案——让你用HTML、CSS和Razor组件构建UI，同时代码直接跑在原生.NET进程里，不经过WebAssembly，不走远程服务器。你的C#代码在设备上原生执行，Razor组件渲染在嵌入式WebView里，两者通过本地通道通信，基本没有网络延迟。

到了.NET 10，Blazor Hybrid已经不再是实验性功能了。微软在这个版本中加入了WebView请求拦截、HybridWebView初始化事件、全局XAML命名空间等重磅特性，再加上NativeAOT和XAML源生成器的加持，整个开发体验和运行时性能都上了一个台阶。

这篇文章会从头到尾带你走一遍完整的开发流程：项目搭建、共享UI架构设计、平台API调用、请求拦截安全实践，一直到性能优化和多平台发布。每个环节都有可以直接用的代码，不搞空洞理论。

Blazor Hybrid架构原理：搞清楚代码到底怎么跑的

在动手之前，先把Blazor Hybrid的运行机制搞明白。这一步省不了——理解架构才能写出正确的代码，出了问题也知道往哪里排查。

核心架构：原生壳 + WebView渲染

Blazor Hybrid应用本质上是一个原生.NET MAUI应用，它通过BlazorWebView控件嵌入了一个WebView来渲染Blazor组件。关键点在于：

所有代码都在原生.NET进程中执行——不用WebAssembly，不走远程服务器
Razor组件的HTML/CSS渲染在WebView里完成（Windows用WebView2、Android用系统WebView、iOS/macOS用WKWebView）
.NET运行时和WebView之间通过本地interop通道通信，延迟可以忽略不计
你可以在同一个页面里混合使用原生MAUI控件和Blazor组件

也就是说，你的Blazor组件可以直接通过依赖注入调用.NET MAUI的平台API（相机、GPS、蓝牙等），不需要像Blazor Server那样走网络请求。说实话，第一次体验这种丝滑调用原生能力的感觉还挺惊喜的。

与其他Blazor托管模型的对比

理解Blazor Hybrid的定位，最好的方式是和其他模型做个对比：

Blazor Server：UI渲染在服务器，通过SignalR实时同步到浏览器。依赖网络，有延迟
Blazor WebAssembly：代码编译成WASM在浏览器沙箱里运行。没法直接访问设备API
Blazor Hybrid：代码在设备原生进程运行，渲染在本地WebView。既有原生能力，又用Web技术构建UI

实测数据（2026年基准）：Blazor Hybrid配合AOT编译，启动时间约2.3秒，空闲内存约85MB，支持完整离线运行，跨平台代码复用率在70%-80%之间。

项目搭建：.NET 10 Blazor Hybrid从零开始

确保你的开发环境装好了.NET 10 SDK和Visual Studio 2022 17.12+（或更高版本）。Windows上还需要WebView2运行时。

创建项目

最直接的方式就是用CLI：

# 创建标准Blazor Hybrid项目
dotnet new maui-blazor -n MyHybridApp

# 或者创建同时包含Web端的完整方案
dotnet new maui-blazor-web -n MyHybridApp

maui-blazor-web模板会生成三个项目：一个.NET MAUI Blazor Hybrid应用、一个Blazor Web App、以及一个共享的Razor类库（RCL）。这个结构是目前的最佳实践——UI组件写一次，移动端和Web端都能用。

项目结构解析

生成的项目结构长这样：

MyHybridApp/
├── MyHybridApp.Maui/          # MAUI Blazor Hybrid 主项目
│   ├── MauiProgram.cs         # 应用入口，注册服务和BlazorWebView
│   ├── MainPage.xaml          # 包含BlazorWebView的原生页面
│   ├── wwwroot/               # 静态资源（CSS、JS、图片）
│   └── Platforms/             # 平台特定代码
├── MyHybridApp.Web/           # Blazor Web App 项目
│   └── Program.cs
├── MyHybridApp.Shared/        # 共享Razor类库（RCL）
│   ├── Components/            # 共享Razor组件
│   ├── Services/              # 共享服务接口
│   └── _Imports.razor         # 全局using声明
└── MyHybridApp.sln

MauiProgram.cs配置

这是整个应用的入口点，核心配置都在这里。来看一下：

using Microsoft.Extensions.Logging;

namespace MyHybridApp.Maui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        // 注册Blazor WebView
        builder.Services.AddMauiBlazorWebView();

#if DEBUG
        // Debug模式下启用开发者工具
        builder.Services.AddBlazorWebViewDeveloperTools();
        builder.Logging.AddDebug();
#endif

        // 注册应用服务
        builder.Services.AddSingleton<ICameraService, CameraService>();
        builder.Services.AddSingleton<ILocationService, LocationService>();
        builder.Services.AddTransient<WeatherViewModel>();

        return builder.Build();
    }
}

MainPage.xaml：BlazorWebView的宿主页面

BlazorWebView控件就是连接MAUI原生世界和Blazor Web世界的那座桥：

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MyHybridApp.Maui"
             x:Class="MyHybridApp.Maui.MainPage"
             BackgroundColor="{DynamicResource PageBackgroundColor}">

    <Grid>
        <!-- Blazor WebView 占满整个页面 -->
        <BlazorWebView x:Name="blazorWebView" HostPage="wwwroot/index.html">
            <BlazorWebView.RootComponents>
                <RootComponent Selector="#app" ComponentType="{x:Type local:Routes}" />
            </BlazorWebView.RootComponents>
        </BlazorWebView>
    </Grid>

</ContentPage>

你也可以在同一个页面里混合原生控件和BlazorWebView——比如顶部放一个原生的NavigationBar，下面用BlazorWebView渲染Blazor内容。在某些场景下这能提供更原生的体验。

共享Razor类库：一套UI组件到处运行

Blazor Hybrid最大的卖点之一就是代码复用。通过Razor类库（RCL），你可以把UI组件写一次，然后在MAUI应用和Web应用里同时使用。不过要把这件事做好，还是需要一些架构设计上的考量的。

核心原则：用接口隔离平台差异

不同平台的能力不同——MAUI应用可以直接调用相机，Web应用只能用浏览器API。解决方案其实很经典：在RCL中定义接口，然后在各个项目中提供平台特定的实现。

// 在共享RCL中定义接口
namespace MyHybridApp.Shared.Services;

public interface ICameraService
{
    Task<string?> TakePhotoAsync();
    bool IsAvailable { get; }
}

public interface ILocationService
{
    Task<LocationResult?> GetCurrentLocationAsync();
}

public record LocationResult(double Latitude, double Longitude, double? Altitude);

// MAUI项目中的实现 - 直接调用原生API
namespace MyHybridApp.Maui.Services;

public class CameraService : ICameraService
{
    public bool IsAvailable => MediaPicker.Default.IsCaptureSupported;

    public async Task<string?> TakePhotoAsync()
    {
        if (!IsAvailable) return null;

        var photo = await MediaPicker.Default.CapturePhotoAsync();
        if (photo is null) return null;

        // 保存到应用缓存目录
        var localPath = Path.Combine(FileSystem.CacheDirectory, photo.FileName);
        using var sourceStream = await photo.OpenReadAsync();
        using var localFileStream = File.OpenWrite(localPath);
        await sourceStream.CopyToAsync(localFileStream);

        return localPath;
    }
}

// Web项目中的实现 - 使用浏览器API
namespace MyHybridApp.Web.Services;

public class WebCameraService : ICameraService
{
    private readonly IJSRuntime _jsRuntime;

    public WebCameraService(IJSRuntime jsRuntime)
    {
        _jsRuntime = jsRuntime;
    }

    public bool IsAvailable => true; // 浏览器通常支持

    public async Task<string?> TakePhotoAsync()
    {
        // 调用浏览器的MediaDevices API
        return await _jsRuntime.InvokeAsync<string?>("cameraInterop.capturePhoto");
    }
}

在Razor组件中使用服务

RCL中的Razor组件通过依赖注入使用服务接口，完全不需要感知底层平台——这是整个共享架构的精髓所在：

@* 共享RCL中的PhotoCapture.razor *@
@inject ICameraService CameraService

<div class="photo-capture">
    @if (CameraService.IsAvailable)
    {
        <button class="btn btn-primary" @onclick="CapturePhoto" disabled="@_isCapturing">
            @(_isCapturing ? "拍摄中..." : "拍照")
        </button>
    }
    else
    {
        <p class="text-muted">当前设备不支持拍照功能</p>
    }

    @if (!string.IsNullOrEmpty(_photoPath))
    {
        <img src="@_photoPath" alt="拍摄的照片" class="captured-photo mt-3" />
    }
</div>

@code {
    private bool _isCapturing;
    private string? _photoPath;

    private async Task CapturePhoto()
    {
        _isCapturing = true;
        try
        {
            _photoPath = await CameraService.TakePhotoAsync();
        }
        finally
        {
            _isCapturing = false;
        }
    }
}

处理渲染模式差异

这里有个小坑需要注意。MAUI Blazor Hybrid应用始终以交互模式运行，不支持指定渲染模式。但如果你的RCL组件同时给Web端用，Web端可能需要指定Server或WebAssembly渲染模式。官方推荐的做法是用一个辅助类来处理：

// 在共享RCL中定义
namespace MyHybridApp.Shared;

public static class InteractiveRenderSettings
{
    // Web端设置为具体的渲染模式，MAUI端设置为null
    public static IComponentRenderMode? InteractiveServer { get; set; }
    public static IComponentRenderMode? InteractiveWebAssembly { get; set; }
    public static IComponentRenderMode? InteractiveAuto { get; set; }
}

// 在MauiProgram.cs中设置为null（MAUI端忽略渲染模式）
InteractiveRenderSettings.InteractiveServer = null;
InteractiveRenderSettings.InteractiveWebAssembly = null;
InteractiveRenderSettings.InteractiveAuto = null;

平台API调用：Blazor组件直通设备能力

Blazor Hybrid相比纯Web方案最大的优势，就是可以直接访问设备原生API。相机、GPS、文件系统、蓝牙、生物认证——.NET MAUI的整个平台抽象层都可以在Blazor组件里直接用。

地理位置服务示例

// MAUI平台实现
public class LocationService : ILocationService
{
    public async Task<LocationResult?> GetCurrentLocationAsync()
    {
        try
        {
            var request = new GeolocationRequest(GeolocationAccuracy.Medium, TimeSpan.FromSeconds(10));
            var location = await Geolocation.Default.GetLocationAsync(request);

            if (location is not null)
            {
                return new LocationResult(location.Latitude, location.Longitude, location.Altitude);
            }
        }
        catch (PermissionException)
        {
            // 权限被拒绝，提示用户
        }
        catch (FeatureNotEnabledException)
        {
            // GPS未开启
        }

        return null;
    }
}

文件选择与分享

文件操作也是Hybrid应用的常见需求，来看看怎么做：

public interface IFileService
{
    Task<FileResult?> PickFileAsync(string[] allowedTypes);
    Task ShareFileAsync(string filePath, string title);
}

public class MauiFileService : IFileService
{
    public async Task<FileResult?> PickFileAsync(string[] allowedTypes)
    {
        var customFileType = new FilePickerFileType(
            new Dictionary<DevicePlatform, IEnumerable<string>>
            {
                { DevicePlatform.iOS, allowedTypes },
                { DevicePlatform.Android, allowedTypes },
                { DevicePlatform.WinUI, allowedTypes },
                { DevicePlatform.macOS, allowedTypes },
            });

        var options = new PickOptions
        {
            PickerTitle = "选择文件",
            FileTypes = customFileType,
        };

        return await FilePicker.Default.PickAsync(options);
    }

    public async Task ShareFileAsync(string filePath, string title)
    {
        await Share.Default.RequestAsync(new ShareFileRequest
        {
            Title = title,
            File = new ShareFile(filePath)
        });
    }
}

生物认证集成

指纹和面部识别这类生物认证，在原生应用里集成起来比Web端简单太多了：

public interface IBiometricService
{
    Task<bool> AuthenticateAsync(string reason);
    bool IsSupported { get; }
}

// MAUI平台实现（需要安装Plugin.Fingerprint NuGet包）
public class BiometricService : IBiometricService
{
    public bool IsSupported => true; // 运行时检测

    public async Task<bool> AuthenticateAsync(string reason)
    {
        try
        {
            var request = new AuthenticationRequestConfiguration("身份验证", reason);
            var result = await CrossFingerprint.Current.AuthenticateAsync(request);
            return result.Authenticated;
        }
        catch
        {
            return false;
        }
    }
}

.NET 10新特性：WebView请求拦截实战

.NET 10给Blazor Hybrid带来了一个期待已久的重磅特性——WebView请求拦截。简单来说，你可以在原生层拦截WebView发出的每一个HTTP请求，修改请求头、重定向URL、甚至直接返回自定义响应。

这个功能最典型的应用场景就是安全Token注入。你不再需要把Access Token暴露给WebView里的JavaScript了，而是在原生层自动给API请求加上认证头。这在安全性上是一个很大的提升。

BlazorWebView请求拦截

// 在MainPage.xaml.cs中设置请求拦截
public partial class MainPage : ContentPage
{
    private readonly ITokenService _tokenService;

    public MainPage(ITokenService tokenService)
    {
        InitializeComponent();
        _tokenService = tokenService;

        // 订阅WebResourceRequested事件
        blazorWebView.BlazorWebViewInitialized += OnBlazorWebViewInitialized;
    }

    private void OnBlazorWebViewInitialized(object? sender, BlazorWebViewInitializedEventArgs e)
    {
        // BlazorWebView初始化完成后设置请求拦截
        blazorWebView.WebResourceRequested += OnWebResourceRequested;
    }

    private async void OnWebResourceRequested(object? sender, WebResourceRequestedEventArgs e)
    {
        // 只拦截发往API服务器的请求
        if (e.Uri?.ToString().StartsWith("https://api.myapp.com") == true)
        {
            e.Handled = true;

            // 获取当前有效的Token
            var token = await _tokenService.GetAccessTokenAsync();

            // 创建带认证头的请求
            using var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Authorization =
                new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);

            var response = await httpClient.GetAsync(e.Uri);
            var content = await response.Content.ReadAsStreamAsync();

            e.SetResponse(
                (int)response.StatusCode,
                response.ReasonPhrase ?? "OK",
                response.Content.Headers.ContentType?.ToString() ?? "application/json",
                content);
        }
    }
}

HybridWebView请求拦截

如果你用的是HybridWebView（用于嵌入传统HTML/JS内容），同样支持请求拦截：

<HybridWebView x:Name="hybridWebView"
               DefaultFile="hybrid/index.html"
               WebResourceRequested="OnHybridWebResourceRequested" />

private void OnHybridWebResourceRequested(object? sender, HybridWebViewWebResourceRequestedEventArgs e)
{
    // 拦截特定资源请求，返回本地缓存的内容
    if (e.Uri?.ToString().Contains("/api/config") == true)
    {
        e.Handled = true;
        var cachedConfig = File.OpenRead(
            Path.Combine(FileSystem.AppDataDirectory, "config_cache.json"));
        e.SetResponse(200, "OK", "application/json", cachedConfig);
    }
}

注意Android平台的限制：Android不支持"拦截后继续"的模式，你只能选择完全替换请求的响应，或者不做任何处理让WebView自行处理。另外Android也不支持自定义URL Scheme。这一点在做跨平台兼容的时候要特别留意。

HybridWebView初始化事件

.NET 10还给HybridWebView加了两个初始化事件，方便你做平台特定的WebView配置：

hybridWebView.WebViewInitializing += (s, e) =>
{
    // WebView创建前触发——配置初始化参数
#if ANDROID
    // Android特定配置
    e.Configuration.AllowContentAccess = true;
#endif
};

hybridWebView.WebViewInitialized += (s, e) =>
{
    // WebView创建后触发——访问原生WebView实例
#if IOS || MACCATALYST
    // iOS/macOS特定配置
    var wkWebView = e.WebView;
    wkWebView.Configuration.Preferences.JavaScriptEnabled = true;
#endif
};

JavaScript互操作：在Blazor和JS之间架桥

虽然Blazor Hybrid让你主要用C#写UI逻辑，但有时候你还是免不了要调用JavaScript——可能是使用某个JS图表库，或者需要调用浏览器的某些特定API。好在.NET MAUI Blazor Hybrid通过IJSRuntime提供了完善的异步JavaScript互操作支持。

C#调用JavaScript

@inject IJSRuntime JSRuntime

@code {
    private async Task InitializeChart()
    {
        // 调用wwwroot/js/chart.js中定义的函数
        await JSRuntime.InvokeVoidAsync("chartInterop.initialize", "chartContainer", _chartData);
    }

    private async Task<string> GetBrowserInfo()
    {
        return await JSRuntime.InvokeAsync<string>("navigator.userAgent");
    }
}

JavaScript调用C#

反过来也可以。JS调用C#方法需要通过DotNetObjectReference来实现：

// Razor组件中暴露C#方法给JS调用
@code {
    private DotNetObjectReference<MyComponent>? _objRef;

    protected override void OnInitialized()
    {
        _objRef = DotNetObjectReference.Create(this);
    }

    [JSInvokable]
    public async Task<string> ProcessDataFromJS(string rawData)
    {
        // 处理从JS传过来的数据
        var result = await DataProcessor.ProcessAsync(rawData);
        return result.ToJson();
    }

    public void Dispose()
    {
        _objRef?.Dispose();
    }
}

性能提示：Blazor Hybrid的JS互操作是异步的（和Blazor Server一样），不支持同步调用。如果你有高频调用的场景，建议批量处理数据，别逐条调用，这样可以减少序列化开销。我之前在一个项目里踩过这个坑，逐条调用导致UI卡顿明显，改成批量后就顺畅多了。

性能优化：让Hybrid应用跑得更快

Blazor Hybrid的性能总体上是够用的——毕竟代码在原生进程里跑，没有网络延迟。但WebView渲染层面还是有一些优化空间的。做好下面这几项，用户体验会有明显提升。

1. 启用AOT编译

NativeAOT在.NET 10中继续优化，iOS端启动速度可以提升近2倍。配合XAML源生成器，Debug构建速度更是提升了100倍（没错，100倍）：

<PropertyGroup>
    <!-- iOS/macOS启用NativeAOT -->
    <PublishAot Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios' OR $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">true</PublishAot>

    <!-- 启用XAML源生成器 -->
    <EnableXamlSourceGenerator>true</EnableXamlSourceGenerator>

    <!-- 启用完全裁剪以减小包体积 -->
    <TrimMode>full</TrimMode>
</PropertyGroup>

2. Blazor组件懒加载

不要把所有组件打包到初始加载中。设置页、报表页、管理后台这些不在首屏显示的页面，用懒加载就好：

@* 路由级别的懒加载 *@
@page "/reports"

@if (_isLoaded)
{
    <ReportDashboard Data="@_reportData" />
}
else
{
    <div class="loading-container">
        <p>加载报表模块...</p>
    </div>
}

@code {
    private bool _isLoaded;
    private ReportData? _reportData;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            _reportData = await ReportService.LoadAsync();
            _isLoaded = true;
            StateHasChanged();
        }
    }
}

3. 减少不必要的重渲染

Blazor的渲染机制是状态一变就重渲染整个组件树。如果你的组件树很深、状态更新又频繁，性能就会下降。用ShouldRender来控制渲染范围：

// 纯展示组件，参数不变就不重渲染
@implements IHandleAfterRender

<div class="data-card">
    <h3>@Title</h3>
    <p>@Value</p>
</div>

@code {
    [Parameter] public string Title { get; set; } = "";
    [Parameter] public string Value { get; set; } = "";

    private string? _previousTitle;
    private string? _previousValue;

    protected override bool ShouldRender()
    {
        // 只有参数真正变化时才重渲染
        if (_previousTitle == Title && _previousValue == Value)
            return false;

        _previousTitle = Title;
        _previousValue = Value;
        return true;
    }

    Task IHandleAfterRender.OnAfterRenderAsync()
    {
        return Task.CompletedTask;
    }
}

4. 列表虚拟化

WebView中渲染大量DOM节点比原生CollectionView消耗更多内存。用Blazor内置的Virtualize组件来虚拟化长列表，效果立竿见影：

<div style="height: 500px; overflow-y: auto;">
    <Virtualize Items="@_allProducts" Context="product" ItemSize="72">
        <div class="product-item">
            <img src="@product.ImageUrl" loading="lazy" alt="@product.Name" />
            <div>
                <strong>@product.Name</strong>
                <span>¥@product.Price.ToString("F2")</span>
            </div>
        </div>
    </Virtualize>
</div>

5. 静态资源优化

WebView加载的CSS、JS和图片都会影响首屏渲染速度，这几个点别忽略：

图片使用WebP格式，配合loading="lazy"延迟加载
CSS和JS文件做压缩和按需加载
字体文件使用font-display: swap避免渲染阻塞
避免在WebView里使用大量复杂CSS动画（这个真的很吃性能）

依赖注入的最佳实践

Blazor Hybrid使用.NET MAUI的内置依赖注入容器，和ASP.NET Core用的是同一套Microsoft.Extensions.DependencyInjection。如果你之前用过ASP.NET Core，这里会非常熟悉。

服务生命周期选择

选对生命周期很重要，选错了可能导致内存泄漏或者状态混乱：

// MauiProgram.cs中的DI注册
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    // Singleton：整个应用生命周期只有一个实例
    // 适合：数据库连接、HTTP客户端、应用状态
    builder.Services.AddSingleton<IAppStateService, AppStateService>();
    builder.Services.AddSingleton<ITokenService, TokenService>();

    // Transient：每次注入都创建新实例
    // 适合：ViewModel、一次性操作服务
    builder.Services.AddTransient<OrderViewModel>();

    // Scoped：在MAUI中行为接近Singleton
    // 注意：MAUI Blazor中Scoped和Singleton行为相似
    builder.Services.AddScoped<IUserSession, UserSession>();

    // HttpClient推荐用IHttpClientFactory管理
    builder.Services.AddHttpClient("ApiClient", client =>
    {
        client.BaseAddress = new Uri("https://api.myapp.com");
        client.DefaultRequestHeaders.Add("Accept", "application/json");
    });

    return builder.Build();
}

平台特定依赖注入

利用条件编译为不同平台注册不同的实现，这是跨平台DI的标准做法：

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

#if ANDROID
    builder.Services.AddSingleton<IPlatformNotification, AndroidNotificationService>();
#elif IOS
    builder.Services.AddSingleton<IPlatformNotification, iOSNotificationService>();
#elif WINDOWS
    builder.Services.AddSingleton<IPlatformNotification, WindowsNotificationService>();
#endif

    return builder.Build();
}

多平台发布注意事项

Blazor Hybrid应用最终就是一个标准的.NET MAUI应用，发布流程和普通MAUI应用一样。但有些Blazor特定的点需要注意。

各平台WebView依赖

Windows：需要WebView2运行时。建议在安装包中内嵌WebView2引导程序，或使用固定版本分发模式
Android：使用系统自带的Android WebView（基于Chromium）。最低支持API Level 24
iOS/macOS：使用WKWebView（基于WebKit/Safari引擎）。注意JavaScript引擎和Chromium有差异，某些JS特性可能表现不同

发布配置

<!-- 发布配置优化 -->
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <!-- 启用完全裁剪 -->
    <PublishTrimmed>true</PublishTrimmed>
    <TrimMode>full</TrimMode>

    <!-- 启用R8/ProGuard（Android） -->
    <AndroidLinkTool>r8</AndroidLinkTool>

    <!-- 压缩wwwroot静态资源 -->
    <BlazorEnableCompression>true</BlazorEnableCompression>
</PropertyGroup>

跨平台CSS兼容性

各平台的WebView引擎不同，你的CSS可能在某些平台上表现不一致。这几条建议能帮你少踩坑：

避免使用仅限Chromium或仅限WebKit的CSS属性
在所有目标平台上测试UI表现（别偷懒只在一个平台上测）
使用CSS自定义属性（CSS变量）处理平台差异
考虑使用-webkit-前缀兼容iOS/macOS的WKWebView

实战项目结构推荐

综合前面所有内容，下面是一个经过生产验证的Blazor Hybrid项目结构。不一定要完全照搬，但核心的分层思路值得参考：

MySolution/
├── src/
│   ├── MyApp.Shared/                    # 共享Razor类库
│   │   ├── Components/
│   │   │   ├── Layout/                  # 布局组件
│   │   │   │   ├── MainLayout.razor
│   │   │   │   └── NavMenu.razor
│   │   │   ├── Pages/                   # 页面组件
│   │   │   │   ├── Home.razor
│   │   │   │   ├── Dashboard.razor
│   │   │   │   └── Settings.razor
│   │   │   └── Shared/                  # 可复用UI组件
│   │   │       ├── DataCard.razor
│   │   │       └── LoadingSpinner.razor
│   │   ├── Services/                    # 服务接口定义
│   │   │   ├── ICameraService.cs
│   │   │   ├── ILocationService.cs
│   │   │   └── IAuthService.cs
│   │   ├── Models/                      # 共享数据模型
│   │   ├── wwwroot/                     # 共享静态资源
│   │   │   ├── css/
│   │   │   └── js/
│   │   └── _Imports.razor
│   ├── MyApp.Maui/                      # MAUI Hybrid项目
│   │   ├── Services/                    # 平台实现
│   │   │   ├── CameraService.cs
│   │   │   └── LocationService.cs
│   │   ├── Platforms/
│   │   └── MauiProgram.cs
│   └── MyApp.Web/                       # Blazor Web项目
│       ├── Services/                    # Web端实现
│       └── Program.cs
└── tests/
    ├── MyApp.Shared.Tests/              # 共享组件测试
    └── MyApp.Maui.Tests/                # MAUI集成测试

常见问题FAQ

Blazor Hybrid和原生.NET MAUI开发该怎么选？

如果你的团队已经有Blazor或者Web开发经验，或者项目需要同时发布移动端和Web端，Blazor Hybrid是更实际的选择——UI组件的复用率可以达到70%-80%。如果应用对渲染性能有极致要求（比如游戏类、动画密集型），或者需要深度定制平台原生UI外观，那原生MAUI开发更合适。

说实话，大多数商业应用的用户几乎感觉不到Hybrid和原生之间的性能差异。

.NET MAUI Blazor Hybrid应用可以离线运行吗？

完全可以。Blazor Hybrid的代码在设备本地运行，不依赖网络。UI渲染在本地WebView中完成，不需要从远程服务器加载。只要你的数据也做了本地持久化（比如用SQLite），应用就可以在完全断网的环境下正常运行。这是它相比Blazor Server和Blazor WebAssembly的明显优势之一。

Blazor Hybrid支持热重载吗？

支持。在开发阶段，.NET MAUI Blazor Hybrid支持XAML和C#代码的热重载。Debug模式下启用AddBlazorWebViewDeveloperTools()后，你可以在运行时修改Razor组件的HTML和CSS并立即看到变化。.NET 10的XAML源生成器还让Debug构建速度提升了100倍，开发体验确实好了不少。

WebView请求拦截功能在所有平台上表现一致吗？

.NET 10引入的WebResourceRequested事件在Windows、iOS和macOS上行为基本一致。但Android平台有个已知限制：它不支持"拦截后继续"模式，你只能完全替换响应或者不做处理。另外Android也不支持自定义URL Scheme。

如果你的应用重度依赖请求拦截，建议在Android平台上做额外测试并准备备用方案。

如何调试Blazor Hybrid中的WebView内容？

各平台的调试方式不太一样。Windows上可以用Edge DevTools直接调试WebView2的内容（右键检查元素或按F12）。Android上需要先在应用配置中启用WebView调试，然后用Chrome的chrome://inspect远程调试。iOS/macOS上则是用Safari的Web Inspector。

不管哪个平台，记得在MauiProgram.cs中调用AddBlazorWebViewDeveloperTools()来启用调试工具支持。

为什么2026年你应该认真考虑Blazor Hybrid？

Blazor Hybrid架构原理：搞清楚代码到底怎么跑的

核心架构：原生壳 + WebView渲染

与其他Blazor托管模型的对比

项目搭建：.NET 10 Blazor Hybrid从零开始

创建项目

项目结构解析

MauiProgram.cs配置

MainPage.xaml：BlazorWebView的宿主页面

共享Razor类库：一套UI组件到处运行

核心原则：用接口隔离平台差异

在Razor组件中使用服务

处理渲染模式差异

平台API调用：Blazor组件直通设备能力

地理位置服务示例

文件选择与分享

生物认证集成

.NET 10新特性：WebView请求拦截实战

BlazorWebView请求拦截

HybridWebView请求拦截

HybridWebView初始化事件

JavaScript互操作：在Blazor和JS之间架桥

C#调用JavaScript

JavaScript调用C#

性能优化：让Hybrid应用跑得更快

1. 启用AOT编译

2. Blazor组件懒加载

3. 减少不必要的重渲染

4. 列表虚拟化

5. 静态资源优化

依赖注入的最佳实践

服务生命周期选择

平台特定依赖注入

多平台发布注意事项

各平台WebView依赖

发布配置

跨平台CSS兼容性

实战项目结构推荐

常见问题FAQ

Blazor Hybrid和原生.NET MAUI开发该怎么选？

.NET MAUI Blazor Hybrid应用可以离线运行吗？

Blazor Hybrid支持热重载吗？

WebView请求拦截功能在所有平台上表现一致吗？

如何调试Blazor Hybrid中的WebView内容？

相关文章

Xamarin.Forms 迁移到 .NET MAUI 完全指南 (2026)：Upgrade Assistant、Handler 与 Shell 实战

.NET MAUI 国际化与本地化完全指南：多语言、RTL与运行时切换实战 (2026)

.NET MAUI 测试完全指南 (2026)：xUnit、Appium 与 Maestro 实战