.NET Native AOT 配置与极端体积优化指南
注： 微软官方从 .NET 7 开始正式引入并支持 Native AOT 编译。因此，本文档介绍的所有基础配置均默认要求目标框架至少为
.NET 7。对于部分在后续版本中新增的配置，已在对应标题后方直接标注（如.NET 8+、.NET 10+）。
因 .NET Native AOT（Ahead-of-Time）编译会将底层的 .NET 运行时（Runtime）、垃圾回收机制（GC）以及所有依赖的框架基础类库（BCL）都静态编译到单一的平台原生可执行文件中，所以编译出的基础二进制文件体积通常比较大。
尽管 AOT 显著降低了应用的启动时间与运行时内存占用，但为了解决打包体积过大的问题，底层的 IL 编译器（ILCompiler）与代码裁剪器（Trimmer）起着决定性作用。通过在 .csproj 中深度微调这些编译参数，我们可以精准剔除不需要的框架子系统（如全球化、反射、网络库等），将最终生成的二进制文件压缩到极致。
1. 核心 AOT 与编译模式
PublishAot
- 作用：控制是否启用 Native AOT 编译，在发布时生成独立的原生可执行文件。
- 适用值：
true/false（默认）。 - 限制：依赖目标操作系统的原生 C++ 编译工具链。目前（截至 .NET 10）只能跨架构编译（如 x64 编译 ARM64），无法跨操作系统平台直接编译（如无法在 Windows 上直接编译 Linux 的二进制文件，需借助 WSL 或容器）。
IsAotCompatible
- 作用：控制是否启用 AOT 兼容性代码分析器。
- 适用值：
true/false（默认）。 - 说明：在开发阶段实时检测并警告使用了不支持 AOT 动态特性（如动态程序集加载、
Reflection.Emit）的代码。
PublishTrimmed
- 作用：控制是否开启未引用代码裁剪。
- 适用值：
true（启用 AOT 时默认为 true） /false。
TrimMode
- 作用：定义代码裁剪的激进程度。
- 适用值：
full（AOT 默认且仅支持此值） /partial。 - 说明：要求应用及其所有引用的 NuGet 包必须是“裁剪安全”的。
- 限制：.NET 8+ AOT 强制要求并仅支持
full模式。
OptimizationPreference （.NET 8+）
- 作用：指示编译器的全局优化倾向，以替代默认的混合优化策略。
- 适用值：
- 留空（默认）：采用混合方法，在生成快速代码和控制应用程序大小之间取得平衡。
Speed：追求理论上的最快执行速度（如激进内联、循环展开），可执行文件体积较大。Size：追求最小二进制体积（如泛型共享、减少内联），可能牺牲少许运行速度。
2. 编译器底层控制 (ILC 配置)
IlcInstructionSet
- 作用：指定目标 CPU 的特定指令集架构以生成优化代码。
- 适用值：目标 CPU 指令集名称（如
avx2、avx512f），默认为空（使用目标架构的基础指令集）。 - 说明：如果强行指定了较新的指令集，生成的文件在不支持该指令集的老旧 CPU 上运行会直接崩溃。
IlcDisableReflection
- 作用：在底层彻底移除运行时的反射基础架构。
- 适用值：
true/false（默认）。 - 说明：这是最为激进的终极体积优化开关。设为
true后，任何调用System.Reflection的代码都会抛出异常，序列化（如 JSON）和依赖注入必须 100% 采用源码生成器（Source Generators）。
IlcScanReflection
- 作用：指示编译器在编译期是否主动扫描代码中的反射模式以保留类型元数据。
- 适用值：
true（默认） /false。 - 说明：配合彻底禁用反射时，设为
false可大幅减少编译耗时与元数据残留。
IlcGenerateStackTraceData
- 作用：控制是否在二进制文件中嵌入异常堆栈的方法名数据。
- 适用值：
true（默认） /false。 - 说明：设为
false可减小体积，但Exception.StackTrace将无法显示具体的方法名。
IlcGenerateCompleteTypeMetadata
- 作用：控制是否生成完整的类型元数据。
- 适用值：
true（默认） /false。 - 说明：设为
false可减小体积，但会破坏部分依赖完整元数据的反射操作。
ControlFlowGuard
- 作用：控制是否启用 CFG（Control Flow Guard）控制流保护，防止内存损坏漏洞。
- 适用值：
Guard/ 留空（默认禁用）。 - 限制：仅限 Windows 平台。
3. 基础类库 (BCL) 特性裁剪
按需剔除 .NET 底层的大型子系统，是缩减体积最有效的方法。以下多数支持属性设为 false 时，可通过移除相关代码来实现极致的体积缩减。
全球化与本地化
InvariantGlobalization
- 作用：控制是否启用全球化不变模式。
- 适用值：
true/false（默认）。 - 说明：设为
true将移除对 ICU 的依赖，体积显著减小。但应用将退化为仅支持“不变文化”（英语），无法处理特定国家语言、日期或货币格式。
HybridGlobalization （.NET 8+）
- 作用：控制是否启用混合全球化模式。
- 适用值：
true/false（默认）。 - 说明：设为
true时调用操作系统原生全球化 API，避免打包庞大的 ICU 数据。 - 限制：仅限 Apple 平台、WASM 以及 Android（Android 需 .NET 9+）。
诊断、监控与调试
DebuggerSupport
- 作用：调试器附加支持。
- 适用值：
true（默认） /false。 - 说明：设为
false将移除调试器支持代码。
EventSourceSupport
- 作用：基于
EventSource的日志记录 (ETW/EventPipe) 支持。 - 适用值：
true（默认） /false。 - 说明：无需复杂遥测的生产环境可设为
false。
MetricsSupport
- 作用：
System.Diagnostics.Metrics（如 OpenTelemetry 指标）支持。 - 适用值：
true（默认） /false。
HttpActivityPropagationSupport
- 作用：
HttpClient的分布式链路追踪支持。 - 适用值：
true（默认） /false。
StackTraceSupport （.NET 8+）
- 作用：异常抛出时的堆栈跟踪字符串格式化支持。
- 适用值：
true（默认） /false。
核心算法与数据结构
UseSizeOptimizedLinq （.NET 10+）
- 作用：控制是否使用针对体积优化过的 LINQ 实现。
- 适用值：
true/false（默认）。 - 说明：设为
true时会牺牲少许运行速度，换取更小的程序集体积。
UseSystemResourceKeys （.NET 8+）
- 作用：控制是否使用简短的资源键名（如
Arg_NullReferenceException）来替代框架抛出的长篇异常提示说明。 - 适用值：
true/false（默认）。 - 说明：设为
true可节省数百 KB 包含长字符串的资源体积。
网络与 XML
Http3Support （.NET 10+）
- 作用：HTTP/3 协议的底层代码支持。
- 适用值：
true（默认） /false。 - 说明：不需要 HTTP/3 时设为
false可移除相关网络代码。
UseNativeHttpHandler
- 作用：控制是否使用操作系统的原生 HTTP 处理器。
- 适用值：
true/false（默认）。 - 说明：设为
true可裁剪掉 .NET 庞大的SocketsHttpHandler托管实现代码。 - 限制：仅限 WASM 和 移动端（iOS/Android/MacCatalyst） 平台。
XmlResolverIsNetworkingEnabledByDefault
- 作用：控制 XML 解析器默认是否允许网络访问。
- 适用值：
true（默认） /false。 - 说明：设为
false有助于裁剪底层的网络依赖模块。
遗留系统与特殊互操作
BuiltInComInteropSupport
- 作用：内置的 COM 互操作支持。
- 适用值：
true（默认） /false。 - 限制：仅限 Windows 平台。
EnableUnsafeUTF7Encoding
- 作用：控制是否启用不安全的 UTF-7 编码支持。
- 适用值：
true/false（较新 .NET 版本中默认已为 false）。
EnableUnsafeBinaryFormatterSerialization
- 作用：控制是否启用高危的
BinaryFormatter序列化组件支持。 - 适用值：
true/false（.NET 8+ 中默认已为 false）。
StartupHookSupport
- 作用：通过环境变量向程序注入代码的启动钩子（Startup Hook）支持。
- 适用值：
true（默认） /false。
MetadataUpdaterSupport
- 作用：Hot Reload（热重载）相关的元数据更新支持。
- 适用值：
true（默认） /false。 - 说明：生产环境 AOT 无需此功能，可设为
false减小体积。
AutoreleasePoolSupport （.NET 8+）
- 作用：隐式
NSAutoreleasePool管理支持。 - 适用值：
true（默认） /false。 - 说明：设为
false可禁用该隐式管理。 - 限制：仅限 Apple 平台（macOS/iOS/MacCatalyst/tvOS）。
4. 裁剪行为干预与警告控制
IsTrimmable
- 作用：指示当前程序集是否为“裁剪安全”。
- 适用值：
true/false（默认）。 - 说明：在自定义类库的
.csproj中设为true，可向编译器宣告此库支持裁剪。
TrimmerRootAssembly
- 作用：强制指定保留整个程序集不被裁剪。
- 适用值：程序集名称（如
MyLib）。 - 说明：此配置属于 MSBuild 的 项 (Item)，需要写在
<ItemGroup>节点中，使用Include属性指定目标。
TrimmerRootDescriptor
- 作用：指定 XML 描述文件以精确保留特定的类和方法不被裁剪。
- 适用值：XML 文件路径（如
TrimmerRoots.xml）。 - 说明：此配置属于 MSBuild 的 项 (Item)，需要写在
<ItemGroup>节点中，使用Include属性指定目标。
SuppressTrimAnalysisWarnings
- 作用：控制是否屏蔽所有的裁剪警告（如
IL2026）。 - 适用值：
true/false（默认）。 - 说明：掩盖警告并不能解决运行时崩溃风险，仅用于确认代码绝对安全的情况。
TrimmerSingleWarn
- 作用：控制是否将每个包含警告的程序集的裁剪警告合并为一条总括性日志输出，以减少控制台噪音。
- 适用值：
true/false（默认）。
5. 调试符号与体积剥离 (Stripping)
DebugSymbols
- 作用：控制是否在构建过程中生成调试符号（
.pdb文件）。 - 适用值：
true（默认） /false。 - 说明：在极限优化中，通常将其设为
false以配合彻底禁用 PDB 生成。
DebugType
- 作用：指定生成的调试符号的格式。
- 适用值：
portable（默认） /embedded/full/none。 - 说明：为了彻底不生成调试符号文件，需将其设为
none，通常与DebugSymbols=false同步使用。
TrimmerRemoveSymbols
- 作用：控制是否在 IL 裁剪阶段彻底移除程序集内残留的符号元数据。
- 适用值：
true（开启裁剪时默认） /false。
StripSymbols
- 作用：控制是否剥离原生二进制文件中的本机调试符号（Native Symbols）。
- 适用值：
true（Linux/macOS 默认） /false。 - 限制：仅限 Linux 和 macOS 平台（Windows 的剥离由底层链接器直接管理）。
6. 原生互操作 (C-ABI 导出)
NativeLib
- 作用：指示编译器不生成可执行程序，而是生成供 C/C++/Rust 调用的库。
- 适用值：
Shared（动态库.dll/.so） /Static（静态库.lib/.a），默认为空（生成可执行文件）。 - 说明：需要导出的 C# 方法必须是
static并标记[UnmanagedCallersOnly]。
CustomNativeMain
- 作用：控制是否由开发者自定义 Native Main 入口点（即防止 C# 自动生成程序的执行入口点）。
- 适用值：
true/false（默认）。 - 说明：通常在静态链接到 C/C++ 项目时使用，由宿主语言编写
main()并初始化运行时。
7. 终极实战：极致体积优化模板
以下配置模板启用了绝大部分的缩减指令。应用此模板可将基础的控制台或 Web API 应用压缩至几 MB 级别。
说明：此配置禁用了反射、全球化和详细异常追踪，部署前需经过严格的运行时测试。
xml
| |