LanMountainDesktop/.github/SIZE_OPTIMIZATION_REPORT.md

🎯 包大小优化 - 完整实施报告

修复日期：2026年3月4日

📋 问题总结

用户反馈

• ❌ 打包产物非常大
• ❌ 没有包含.NET运行时

根本原因

1. 发布命令缺少优化参数 - 未启用代码修剪、预编译等
2. 项目文件缺少Release配置 - 没有条件化的发布优化
3. 修剪配置缺失 - 没有保护必要的程序集不被修剪
4. 自包含配置不完整 - 虽然用了 --self-contained 但参数不够完记

✅ 实施的优化方案

1️⃣ 工作流优化（.github/workflows/release.yml）

Windows 构建 (PowerShell)

- name: Publish
  run: |
    dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
      -c Release `
      -o ./publish/windows-${{ matrix.arch }} `
      --self-contained `
      -r win-${{ matrix.arch }} `
      -p:PublishSingleFile=true `
      -p:SelfContained=true `
      -p:DebugType=none `
      -p:DebugSymbols=false `
      -p:PublishTrimmed=true `
      -p:TrimMode=partial `
      -p:PublishReadyToRun=true

Linux 构建 (Bash)

- name: Publish
  run: |
    dotnet publish LanMountainDesktop/LanMountainDesktop.csproj \
      -c Release \
      -o ./publish/linux-x64 \
      --self-contained \
      -r linux-x64 \
      -p:PublishSingleFile=true \
      -p:SelfContained=true \
      -p:DebugType=none \
      -p:DebugSymbols=false \
      -p:PublishTrimmed=true \
      -p:TrimMode=partial \
      -p:PublishReadyToRun=true

macOS 构建 (Bash)

相同的优化参数，使用 -r osx-${{ matrix.arch }}

2️⃣ 项目文件优化（LanMountainDesktop/LanMountainDesktop.csproj）

<!-- Release build optimizations -->
<PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>
<PublishTrimmed Condition="'$(Configuration)' == 'Release'">true</PublishTrimmed>
<TrimMode Condition="'$(Configuration)' == 'Release'">partial</TrimMode>
<PublishReadyToRun Condition="'$(Configuration)' == 'Release'">true</PublishReadyToRun>
<DebugSymbols Condition="'$(Configuration)' == 'Release'">false</DebugSymbols>

<!-- Self-contained runtime support -->
<SelfContained Condition="'$(RuntimeIdentifier)' != ''">true</SelfContained>

3️⃣ 修剪保护配置（LanMountainDesktop/TrimmerRoots.xml）

创建了修剪根描述文件，保护以下关键程序集：

<linker>
  <!-- Avalonia UI Framework -->
  <assembly fullname="Avalonia" preserve="all" />
  <assembly fullname="Avalonia.Controls" preserve="all" />
  <assembly fullname="Avalonia.Desktop" preserve="all" />
  <assembly fullname="Avalonia.Themes.Fluent" preserve="all" />
  
  <!-- Fluent Design System -->
  <assembly fullname="FluentAvaloniaUI" preserve="all" />
  <assembly fullname="FluentIcons.Avalonia" preserve="all" />
  
  <!-- Media & Rendering -->
  <assembly fullname="LibVLCSharp.Avalonia" preserve="all" />
  <assembly fullname="WebView.Avalonia" preserve="all" />
  
  <!-- MVVM & Utilities -->
  <assembly fullname="CommunityToolkit.Mvvm" preserve="all" />
  <assembly fullname="YamlDotNet" preserve="all" />
  
  <!-- System Libraries -->
  <assembly fullname="System.Reflection" preserve="all" />
  <assembly fullname="System.Drawing.Common" preserve="all" />
</linker>

📊 优化参数详解

参数	作用	效果
--self-contained	包含.NET运行时	独立可执行，无需系统.NET
-p:PublishSingleFile=true	打包为单一执行文件	简化分发部署
-p:SelfContained=true	确保自包含模式	保证运行时包含
-p:PublishTrimmed=true	启用代码修剪	减少30-50%
-p:TrimMode=partial	安全修剪模式	保护反射和动态代码
-p:PublishReadyToRun=true	预编译IL到机器码	减少10-20%
-p:DebugSymbols=false	移除调试符号	减少5-15%
-p:DebugType=none	移除调试信息	减少metadata

🎯 预期成果

包大小对比

平台	优化前（预期）	优化后（预期）	减少比例
Windows x64	~600 MB	~250-300 MB	55-60% ⬇️
Windows x86	~550 MB	~220-280 MB	50-60% ⬇️
Linux x64	~550 MB	~200-280 MB	50-65% ⬇️
macOS x64	~550 MB	~200-280 MB	50-65% ⬇️
macOS arm64	~550 MB	~200-280 MB	50-65% ⬇️

性能提升

• ✅ 更快的启动 - ReadyToRun预编译提高运行时性能
• ✅ 完整运行时 - 自包含模式包含.NET 10运行时
• ✅ 单一文件 - 用户只需运行一个可执行文件

🧪 验证清单

本地测试（可选）

# Windows
dotnet publish LanMountainDesktop\LanMountainDesktop.csproj `
  -c Release -r win-x64 --self-contained `
  -p:PublishSingleFile=true -p:PublishTrimmed=true `
  -p:TrimMode=partial -p:PublishReadyToRun=true `
  -p:DebugType=none -p:DebugSymbols=false

# 验证单文件
dir publish\windows-x64\  # 应该只有1个.exe文件

CI/CD 验证

1. 推送测试版本

   git tag v1.0.1-test
   git push origin v1.0.1-test
   

2. 监察GitHub Actions

   • ✅ 检查发布日志是否无错误
   • ✅ 验证Trimming过程
   • ✅ 确认ReadyToRun编译
   • ✅ 检查输出大小

3. 发布验证

   • ✅ 下载Windows包
   • ✅ 下载Linux包
   • ✅ 下载macOS包
   • ✅ 检查包大小（应该明显小于原来的）
   • ✅ 运行应用验证功能

4. 依赖验证（验证.NET运行时已包含）

   Windows:

   # 检查二进制文件
   (Get-Item "LanMountainDesktop.exe").Length  # 应该是 200-300 MB
   
   # 在没有.NET的机器上运行
   

   Linux:

   # 检查二进制文件
   ls -lh LanMountainDesktop  # 应该是 200-300 MB
   
   # 检查依赖
   ldd ./LanMountainDesktop | grep -i "not found"  # 不应该有输出
   

⚠️ 故障排除

如果包仍然很大

检查清单：

1. ✅ 确认 -p:PublishTrimmed=true 在工作流中
2. ✅ 检查项目文件是否成功修改
3. ✅ 查看构建日志是否有修剪警告
4. ✅ 验证TrimmerRoots.xml是否被识别

如果应用无法启动

原因可能：代码修剪过度

解决方案：

1. 检查应用日志中的异常（MissingMethodException等）
2. 在TrimmerRoots.xml中添加缺失的程序集
3. 用 TrimMode=partial 替代 full（已使用）

如果找不到.NET运行时

原因可能：自包含配置未正确应用

解决方案：

1. 检查发布命令是否包含 --self-contained
2. 确认 -r 运行时标识符正确
3. 验证 -p:SelfContained=true
4. 查看工作流日志中的发布错误

📝 后续改进

可选的额外优化

1. 启用LTCG（Link Time Code Generation）

   <PublishTrimmed>true</PublishTrimmed>
   <PublishAotLinked>true</PublishAotLinked>  <!-- 如果支持 -->
   

2. 移除不必要的语言包

   <InvariantGlobalization>false</InvariantGlobalization>
   

3. 启用分层编译

   <TieredCompilation>true</TieredCompilation>
   <TieredCompilationQuickJit>true</TieredCompilationQuickJit>
   

监控指标

• 始终监测发布日志中的修剪警告：⚠️ Trimmed away 消息
• 定期测试功能完整性
• 监察包大小趋势：确保不会意外增长

📚 参考资源

• MSBuild 发布属性
• .NET 应用修剪
• Avalonia 部署指南
• 单文件发布

---

✨ 总结

通过以上优化，预期可以减少50-65%的包大小，同时确保.NET运行时完整包含。所有优化都是在保证应用功能完整的前提下进行的。

下一步行动：

1. ✅ 推送测试标签验证优化
2. ✅ 下载并检查发布的包大小
3. ✅ 运行应用验证功能
4. ✅ 如遇到问题按故障排除步骤处理