.NET MAUI Blazor Hybrid混合开发指南：从搭建到多平台发布

为什么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()来启用调试工具支持。