LanMountainDesktop/docs/AOT_PUBLISH.md

Launcher AOT 单文件发布指南

什么是 AOT？

AOT（Ahead-of-Time）编译将 .NET 代码在构建时直接编译为本地机器码，而不是在运行时通过 JIT 编译。

AOT 的优势

特性	JIT 模式	AOT 模式
启动速度	慢（需要编译）	快（直接执行）
依赖文件	多（.dll, runtimeconfig.json）	少（单文件）
需要 .NET Runtime	是	否
文件体积	小	稍大（但单文件更方便）
反编译难度	容易	困难

发布方式

方式一：使用 PowerShell 脚本（推荐）

# 默认发布（win-x64，单文件，自包含）
.\scripts\Publish-AOT.ps1

# 指定运行时
.\scripts\Publish-AOT.ps1 -RuntimeIdentifier win-x64

# 不压缩（体积更大但启动更快）
.\scripts\Publish-AOT.ps1 -Compress:$false

方式二：使用 dotnet CLI

# 基本 AOT 发布
dotnet publish LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj `
  -c Release `
  -r win-x64 `
  --self-contained `
  -p:PublishAot=true `
  -p:PublishSingleFile=true `
  -p:EnableCompressionInSingleFile=true

# 输出目录
# bin/Release/net10.0/win-x64/publish/

方式三：使用 MSBuild

msbuild LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj `
  /t:Publish `
  /p:Configuration=Release `
  /p:RuntimeIdentifier=win-x64 `
  /p:PublishAot=true `
  /p:PublishSingleFile=true

支持的运行时

运行时标识符	说明
win-x64	Windows 64位（推荐）
win-x86	Windows 32位
win-arm64	Windows ARM64
linux-x64	Linux 64位
linux-arm64	Linux ARM64
osx-x64	macOS 64位
osx-arm64	macOS ARM64 (Apple Silicon)

文件体积对比

普通发布（非 AOT）

LanMountainDesktop.Launcher.exe       150 KB
LanMountainDesktop.Launcher.dll       200 KB
Avalonia.dll                          1.2 MB
...（数十个依赖文件）
总计: ~15 MB

AOT 单文件发布

LanMountainDesktop.Launcher.exe       8-12 MB（单文件，包含所有依赖）

注意事项

1. 修剪（Trimming）

AOT 会自动移除未使用的代码以减小体积。某些反射代码可能需要特殊处理：

// 如果类型被反射使用，需要保留
[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)]
public class MyClass { }

2. Avalonia 兼容性

• ✅ Avalonia 11.x 完全支持 AOT
• ✅ 使用 Compiled Bindings（已在项目中启用）
• ✅ 避免动态 XAML 加载

3. Json 序列化

使用 JsonSerializer 时需要源生成器：

[JsonSerializable(typeof(MyType))]
internal partial class MyJsonContext : JsonSerializerContext { }

4. 单文件特殊处理

某些文件需要嵌入到单文件中：

<ItemGroup>
  <EmbeddedResource Include="Assets\logo.ico" />
</ItemGroup>

故障排除

发布失败

1. 检查 .NET SDK 版本

   dotnet --version  # 需要 10.0 或更高
   

2. 安装 AOT 工作负载

   dotnet workload install wasm-tools  # 如果需要 WebAssembly AOT
   

3. Visual Studio 要求

   • 需要 VS 2022 17.8+ 或 VS Code + C# Dev Kit

运行时错误

1. 缺少类型

   • 在 .csproj 中添加 <TrimmerRootAssembly>

2. 反射失败

   • 使用 [DynamicallyAccessedMembers] 标记

3. DllNotFoundException

   • 确保所有 native 库都包含在发布中

性能对比

指标	JIT	AOT	提升
启动时间	2-3 秒	0.5-1 秒	2-3x
内存占用	较高	较低	20-30%
首次响应	慢	快	显著

推荐配置

对于 Launcher 项目，推荐使用以下配置：

<PublishAot>true</PublishAot>
<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>
<SelfContained>true</SelfContained>
<PublishSingleFile>true</PublishSingleFile>
<IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
<EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>

这样发布的结果：

• ✅ 单文件可执行
• ✅ 无需 .NET Runtime
• ✅ 启动速度快
• ✅ 文件体积合理（8-12 MB）