Avalonia 11升级12，使用 SukiUI + MapUI + WebView 完整升级指南

我直接给你最实战、可落地、全覆盖 的升级清单，包含必须改的代码 、包版本 、坑点 、WebView 集成方案，你照着改就能跑通。

一、先明确核心兼容关系（最重要）

Avalonia 12 生态有强版本依赖，必须全部对齐，否则直接崩溃：

表格

库	适配 Avalonia 12 的正确版本
Avalonia	12.0.x 最新
SukiUI	7.0+（6.0 不支持 Avalonia 12！）
MapUI	5.1+（5.0 不支持 Avalonia 12）
WebView	Avalonia.WebView / Web.Avalonia 必须用 12.x 版本

致命问题：SukiUI 6.0 完全不兼容 Avalonia 12，必须升级 SukiUI！

---

二、第一步：升级 NuGet 包（必须全部替换）

1. 卸载旧包

plaintext

Avalonia* 11.x
SukiUI 6.0
MapUI 5.0

2. 安装新包（复制即可）

xml

<!-- Avalonia 12 -->
<PackageReference Include="Avalonia" Version="12.0.9" />
<PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.9" />
<PackageReference Include="Avalonia.Fonts.Inter" Version="12.0.9" />

<!-- SukiUI 7.x（支持 Avalonia12） -->
<PackageReference Include="SukiUI" Version="7.0.0" />
<PackageReference Include="SukiUI.Controls" Version="7.0.0" />

<!-- MapUI 5.1+（支持 Avalonia12） -->
<PackageReference Include="MapUI" Version="5.1.0" />
<PackageReference Include="MapUI.Avalonia" Version="5.1.0" />

<!-- WebView（Avalonia12 专用） -->
<PackageReference Include="Avalonia.WebView" Version="12.0.0" />
<PackageReference Include="Avalonia.WebView.Windows" Version="12.0.0" />
<!-- 跨平台可选：Linux/macOS -->
<PackageReference Include="Avalonia.WebView.Linux" Version="12.0.0" />
<PackageReference Include="Avalonia.WebView.Mac" Version="12.0.0" />

---

三、代码必须修改的地方（Avalonia 11 → 12 破坏性变更）

1. Program.cs/ App.cs 主程序变更

Avalonia 12 移除了 UseSkia ，简化了 AppBuilder。

旧代码（11）

csharp

运行

public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .UseSkia()  // 12 已删除
        .UseReactiveUI()
        ...

新代码（12）

csharp

运行

public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .UseSkia()  // 可留，也可删
        .UseWebView() // WebView 必须加
        .UseSukiUI() // SukiUI7 必须加
        ...

2. SukiUI 6.0 → 7.0 重大变更（必须改）

SukiUI 7 重构了主题、命名空间、控件注册方式：

1）App.axaml 样式引入

旧（6.0）

xml

<StyleInclude Source="avares://SukiUI/Theme.axaml" />

新（7.0）

xml

<suki:SukiTheme />

2）命名空间变更

xml

xmlns:suki="clr-namespace:SukiUI;assembly=SukiUI"
xmlns:sukiControls="clr-namespace:SukiUI.Controls;assembly=SukiUI"

3）主题初始化代码（App.cs）

csharp

运行

SukiTheme.GetInstance().Activate();
SukiTheme.GetInstance().ChangeBaseTheme(ThemeVariant.Dark);

3. MapUI 5.0 → 5.1 适配 Avalonia12

MapUI 5.1 修复了 Avalonia12 渲染问题，API 基本没变，只需要：

• 升级包到 5.1
• 确保 MapControl 正常引用
• 无需改业务代码

4. WebView 集成代码（Avalonia12 专用）

1）在 AppBuilder 注册

csharp

运行

.UseWebView()

2）页面使用

xml

<WebView Url="https://www.baidu.com"
         Width="800"
         Height="600"/>

3）平台初始化（Windows 必须）

在 Program.cs 顶层加入：

csharp

运行

[assembly: WebViewPlatformSupport]

---

四、Avalonia 12 强制语法变更（你 100% 会遇到）

1. [Observable] 属性变更（Avalonia 12 不再自带）

Avalonia 12 拆出了 ReactiveUI / SourceGenerator，必须手动安装：

plaintext

<PackageReference Include="Avalonia.Generators" Version="12.0.9" />

2. 控件命名变更

• TextBlock → 保留
• TextBox → 保留
• Window 无变化
• ContentControl 模板渲染逻辑变化

3. Styles / Themes 结构强制变更

Avalonia12 不再兼容旧版 FluentTheme 写法：

旧

xml

<FluentTheme Mode="Dark"/>

新

xml

<FluentTheme Variant="Dark" />

4. 几何图形、图标渲染变更

SukiUI 6.0 的图标在 12 上会不显示 / 崩溃，升级 SukiUI7 后自动修复。

---

五、升级后最常见的崩溃 / 异常（提前告诉你怎么解决）

1. 直接崩溃：System.TypeInitializationException

原因 ：SukiUI 6.0 + Avalonia12 不兼容 解决：必须升级 SukiUI → 7.0

2. WebView 找不到程序集

原因 ：缺少 .Windows / .Linux 运行时包 解决：安装对应平台的 WebView 包

3. 地图 MapControl 空白 / 不渲染

原因 ：MapUI 5.0 不支持 Avalonia12 解决：升级 MapUI → 5.1+

4. 样式丢失、主题不生效

原因 ：SukiUI7 主题注册方式变了 解决：按上面 SukiUI 部分重新注册

5. 编译报错：UseSkia () 不存在

解决 ：直接删掉 .UseSkia()，Avalonia12 默认启用

6. 绑定失效、ViewModel 不工作

解决 ：安装 Avalonia.Generators，重新生成项目

---

六、完整可运行的 App.cs（最终版）

csharp

运行

using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Markup.Xaml;
using SukiUI;
using Avalonia.WebView;

namespace YourProject
{
    public partial class App : Application
    {
        public override void Initialize()
        {
            AvaloniaXamlLoader.Load(this);
            SukiTheme.GetInstance().Activate();
        }

        public override void OnFrameworkInitializationCompleted()
        {
            if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
            {
                desktop.MainWindow = new MainWindow();
            }
            base.OnFrameworkInitializationCompleted();
        }

        public static AppBuilder BuildAvaloniaApp()
            => AppBuilder.Configure<App>()
                .UsePlatformDetect()
                .UseWebView()
                .UseSukiUI()
                .UseSkia()
                .WithInterFont()
                .LogToTrace();
    }
}

---

七、最简升级步骤总结（你照着执行）

1. 卸载所有 Avalonia11、SukiUI6、MapUI5 包
2. 安装我给的 Avalonia12 + SukiUI7 + MapUI5.1 + WebView12 包
3. 修改 AppBuilder，加入 .UseWebView() + .UseSukiUI()
4. 修改 SukiUI 主题注册方式
5. 修复编译错误（删除 UseSkia、更新命名空间）
6. 运行 → 成功

---

总结

1. SukiUI 6.0 不支持 Avalonia12 ，必须升级到 7.0+
2. MapUI 5.0 不支持 Avalonia12 ，必须升级到 5.1+
3. WebView 必须使用 Avalonia12 专用版本
4. 代码改动集中在：主程序构建、样式注册、命名空间
5. 所有崩溃 99% 都是包版本不匹配导致