先说一个让我决定把这套东西彻底搞清楚的场景。前阵子把一个内部小工具发布成自包含单文件顺手开了裁剪产物从 30 多 MB 压到 10 MB 出头启动也快了不少。结果工具跑到第三个业务分支直接抛了一个MissingMethodException。查到最后是一个按字符串反射查类型的辅助方法开发环境跑得一切正常裁剪之后元数据被删了方法也就没了。从那天起我把 Native AOT、裁剪和源生成器这三件事放在一起重新理了一遍才意识到它们根本不该分开看Native AOT 和 Trimming 负责把绝大多数运行时才知道的东西压缩掉而 Source Generators 负责在编译期把这些信息重新补回来。这套组合现在团队内部简称为 NTLs也就是标题里那个缩写。这篇内容适合三类人被dotnet publish出来的幽灵异常折磨过的开发想给类库做 AOT/裁剪兼容的作者以及要在启动时间、包体积上有硬指标的交付团队。我尽量少讲废话把原理、坑位和能直接抄的改造路径都放进来。1. 为什么裁剪 AOT 源生成器必须放在一起讲1.1 裁剪的底层逻辑静态可达性扫描裁剪Trimming本质上是一个保守的删减器。发布时工具先从程序入口点开始沿着 IL 里的方法调用、字段访问、类型引用等静态线索画出一张可达性图然后保留这张图里能触达的所有类型和成员其余的一律从程序集中移除。因为它是静态扫描所以只能看到代码里写死的信息。用搬家来类比裁剪工在做的事是把你房间里明面上能看见的东西打包带走。你只要在物品上贴了标签或者放在一个能看得见的箱子里它就能带走。可反射是什么反射是你在纸上写了一句我可能要用到某个柜子里的第三格东西然后把纸条揣进兜里。搬家工人根本看不见这张纸条自然以为柜子是不需要的东西直接扔了。所以很多项目开发环境一切正常开裁剪后隔三差五崩原因几乎都出在同一条链路上反射字符串、按类型全名查找成员、PropertyInfo.GetValue()这些在 IL 里不是对某个目标方法的直接引用而是对字符串或Type对象的操作。静态扫描工具无法从Type.GetType(SomeNamespace.SomeService)这个字符串里推算出你真正要用哪个类型。结果就是发布成功运行到那一行为止直接塌方。1.2 没有 JIT 的世界动态代码能力从根上消失如果说裁剪是把可能用到的元数据删掉那 Native AOT 更狠它连运行时解释 IL 的机制都不留。普通发布模式下程序集里装的还是 IL 和元数据运行时用 JIT 按需编译甚至可以动态生成代码比如AssemblyBuilder、Reflection.Emit、运行时拼接表达式。但 Native AOT 在发布阶段就把 IL 直接编译成了本机代码目标机器上不再有托管运行时替你兜底。这带来一个很直接的后果凡是依赖运行时生成 IL的功能在 AOT 下要么抛异常要么行为完全不可用。常见的Activator.CreateInstance(Type)配合某个动态构造的类型在普通运行环境还行一旦进入 AOT 环境那个Type对象背后连可执行的元数据都没有自然没法实例化。更麻烦的是很多第三方库在初始化路径里藏了这类动态操作不跑到那一步根本发现不了。从工程角度看裁掉的是多余的元数据AOT 限制的是运行时动态解析能力。两者叠加之后代码里任何等运行时再去查名字、找方法、生成调用的写法全部变成高危行为。而源生成器之所以成为 NTLs 的第三块拼图就是因为它把这类运行时查表动作硬生生前移到了编译器阶段。1.3 三者的互补关系把运行时猜测变成编译期已知传统反射链路是程序运行时拿到一个Type然后靠元数据去查成员、调用。源生成器则是反过来的思路编译时Roslyn 编译器已经把源代码里的类型符号看得一清二楚生成器拿到这些符号直接帮你生成一段硬编码的代码。这段生成代码编译进程序集后就是普通的方法调用和属性访问同理可被 AOT 编译器正常处理。一个特别直观的例子是序列化。以前写一个通用 JSON 序列化器往往用T.GetType()加GetProperties()遍历运行期动态取值。改成源生成器的做法后生成器会在编译期看到对象的所有属性为每个类型生成一段固定代码访问value.Name这种直接成员引用。裁剪时能看到这段代码用到了哪个字段、哪些属性自然会把它们保留下来AOT 编译时也不需要任何动态生成能力。所以我在排查问题时有个习惯遇到运行期反射链就先去想这个信息编译期是否已经存在。如果存在那大概率能用源生成器解决如果不存在才轮到DynamicallyAccessedMembers注解、裁剪根配置等手段保命。优先顺序从来不是反射而是能生成就生成。2. 裁剪与 AOT 到底会拆掉哪些平时看不见的能力2.1 反射调用与 IL 警告先看懂编译器在喊什么开裁剪后编译器往往会在输出里给出一堆IL2026、IL2057、IL207x这类警告。这些不是普通建议而是裁剪分析和 AOT 编译器在告诉你这里存在动态访问模式发布后可能崩。我见过太多项目把这些警告当噪音忽略最后全变成线上事故所以先花点时间看懂它们。IL2026调用了某个标注了RequiresUnreferencedCode的成员说明这一调用点在裁剪环境下不安全。IL2057出现了编译器无法静态解析的反射模式最常见的就是字符串拼接出类型名传给Type.GetType。IL2072/IL2075/IL2080多和DynamicallyAccessedMembers注解相关表示某个值的动态成员需求无法被满足。一个典型代码长这样[RequiresUnreferencedCode(通过反射校验任意对象裁剪后可能失效)] public void ValidateByReflection(object target) { Type t target.GetType(); var prop t.GetProperty(Status); object? value prop?.GetValue(target); if (value ! null !Convert.ToBoolean(value)) { throw new InvalidOperationException(校验未通过); } }只要编译时看到这段裁剪分析器就会警告GetProperty(Status)是字符串查找linker 不知道你是否还需要属性 Status。所以这类代码要么改成直接强类型访问要么给调用方传播这里不安全的信号让调用方自己决定怎么处置。2.2 动态程序集、Emit 与运行时模板的边界另一个大坑是动态程序集。以前有些框架喜欢在启动时Assembly.LoadFrom一个插件目录里的托管 DLL然后用反射扫出所有实现某个接口的类型。普通运行时里这是很常规的路数甚至很多插件化架构都这么干。但遇到 AOT这套直接失效发布产物里根本不可能带一个能加载并执行任意托管 DLL 的运行时环境。托管插件只能换成其他方案比如编译成本机动态库做进程外调用或者在编译期就把插件类型通过源生成器注册进来。还有一批 API 是看着像普通方法调用实际挂在动态能力上的。比如AssemblyBuilder、ModuleBuilder运行时构造程序集AOT 下不可用。Expression.Compile()如果表达式的解析内容涉及大量反射成员查找部分场景在 AOT 下也会被卡住。各种基于Activator.CreateInstance(type, args)的通用工厂函数只要type不是编译期常量基本都会遇到问题。早些时候我在某个模拟项目 X 里写过一个配置系统配置文件的PluginType字段存的是程序集限定名运行时Type.GetType加载插件。这个写法在 Windows 开发机上跑得一帆风顺一开PublishTrimmed就完蛋。这就是 2.1 节说的 IL2057 警告的典型来源只不过那时我对警告不敏感把风险一直带到了交付阶段。2.3 一次发布成功但运行崩的完整复盘那次事故的排查路径值得完整复述一遍。工具发布后用户反馈一点某个菜单就退出。我用事件日志抓下来异常是System.MissingMethodException: Method not found: ConfigLib.PluginFactory.Create.第一反应是版本不一致检查了半天发现所有程序集版本都对得上。后来把发布配置的PublishTrimmed关掉再发一版问题消失。这时候才确定是裁剪干的。顺着源码找发现创建插件的代码是这样的object obj Activator.CreateInstance( Type.GetType(entry.PluginTypeName, throwOnError: true) ?? typeof(object));问题很清晰PluginTypeName是配置文件里的字符串裁剪扫描永远看不到这个类型名所以PluginFactory.Create这个成员直接被删了。而开发环境没裁剪元数据齐全自然能用。最后我做了三件事给插件的类型清单改成显式注册表用一个字典把插件名映射到typeof(XxxFactory)这样的静态引用对必须按名字动态找的类型补了 XML 裁剪根描述文件把编译器对反射的动态访问警告全部留档禁止带警告发布。从那以后我对 NTLs 的理解就不只是三个名词放一起而是一条完整的安全防线。3. 源生成器如何从根上化解裁剪的误杀3.1 源生成器接入 Roslyn 编译管线的位置源生成器本质上是编译器的插件。正常的编译顺序是源码被分词、解析成语法树然后进入语义分析生成 IL。源生成器挂在语法树和语义分析之间它能看到当前编译单元里所有类型的符号信息并根据这些符号生成额外的 C# 代码拼到这次编译里。最早一批生成器要手动写ISyntaxReceiver比较麻烦。现在推荐直接用ForAttributeWithMetadataName这种增量 API只要某个类型上挂着指定全名的特性生成器就能拿到它的INamedTypeSymbol然后生成代码。写一个最简单的生成器骨架大概是这样[Generator] public sealed class MapToTextGenerator : IIncrementalGenerator { public void Initialize(IncrementalGeneratorInitializationContext context) { var targets context.SyntaxProvider.ForAttributeWithMetadataName( NtlsDemo.MapToTextAttribute, predicate: static (node, _) node is TypeDeclarationSyntax, transform: static (ctx, _) (INamedTypeSymbol)ctx.TargetSymbol) .Collect(); context.RegisterSourceOutput(targets, static (spc, symbols) { foreach (var symbol in symbols.Distinct(SymbolEqualityComparer.Default)) { spc.AddSource(${symbol.Name}.g.cs, BuildCode(symbol)); } }); } }注意生成器本身要编译成一个独立程序集目标框架通常是netstandard2.0消费者项目通过ProjectReference OutputItemTypeAnalyzer ReferenceOutputAssemblyfalse /引用它。这样生成器只在编译期运行不会被带进最终产物也不参与运行时的任何动态行为。3.2 从类型符号到生成代码的完整链路继续拿那个生成器举例子。假设我们手里有一个类需要自动生成把对象转成文本的方法。原始类型[MapToText] public partial class Person { public string? Name { get; set; } public int Age { get; set; } }生成器拿到Person这个INamedTypeSymbol后遍历它的公共属性拼出一个扩展方法访问value.Name、value.Age这种直接成员。生成代码长这样// auto-generated/ using System.Text; namespace NtlsDemo { public static partial class PersonExtensions { public static string ToText(this Person value) { var sb new StringBuilder(); sb.Append(Name); sb.Append(value.Name); sb.Append(Age); sb.Append(value.Age); return sb.ToString(); } } }注意两个关键点一是生成代码里的value.Name是强类型成员访问不是反射查找二是被标记的类必须声明为partial生成代码才能和用户代码合并到同一个类型里。这两点做得对裁剪扫描就能看见所有被访问的属性AOT 编译也不需要任何运行时反射能力。从整个链路看用户在源码里写属性 → Roslyn 把属性符号暴露给生成器 → 生成器把读属性的行为固化成 IL 里的直接访问指令 → 裁剪保留这些指令涉及到的成员 → AOT 直接编译。这才是 NTLs 真正的威力所在把本来要依赖运行时元数据的事情转移到编译期一次性做完。3.3 为什么源生成器天然裁剪安全源生成器之所以被 AOT 项目偏爱不是因为它的 API 有多炫而是因为它完全避开了运行时查表这一步。运行时反射需要Assembly、Type、MethodInfo这些元数据对象常驻内存裁剪后的程序集恰恰在压缩这些而生成代码不需要元数据它只需要编译后的字段偏移和函数地址这对 AOT 来说是再舒服不过的输入。这也解释了为什么现在生态里大量组件都在往源生成方向迁移。比如很多 JSON 序列化库都提供了源生成上下文模式在某个partial类上声明你需要序列化哪些类型编译期就生成对应的序列化代码。发布到 AOT 环境下这些序列化器是硬编译出来的不会触发裁剪警告也不会在运行时找属性。这种声明式 编译期生成的模式基本成了类库支持 AOT 的标准形态。但这里必须泼一盆冷水源生成器不是银弹。它解决的是编译期可以看见的类型。如果你业务里确实存在用户运行时自己拼类型名、或者从外部模块动态加载类型这类需求源生成器帮不了你只能靠更粗粒度的裁剪根配置或者进程外插件方案。判断标准还是那句信息是否在编译期已经确定。4. 实战把一个反射序列化模块改造成源生成器驱动4.1 改造前的反射实现与风险点很多项目里都会有一个把任意对象转成文本/KV这种小工具。反射版写起来很快public static string ConvertToText(object value) { var type value.GetType(); var sb new StringBuilder(); foreach (var p in type.GetProperties()) { sb.Append(p.Name).Append().Append(p.GetValue(value)).Append(;); } return sb.ToString(); }缺点一眼就能看出来type.GetProperties()返回哪些属性取决于运行时元数据里留下了哪些p.GetValue(value)是动态调用。开裁剪后哪怕value是Person只要Person的属性没有被其他静态代码直接访问就可能被剪掉运行时拿到的是空属性列表。就算属性侥幸保留了每次GetValue还有装箱、反射调用、安全检测的开销性能也不好看。改造的逻辑很简单我要的是给指定的强类型生成一段遍历属性的代码。这正好是源生成器的舒适区。于是把通用反射版本替换成特性标记 生成扩展方法调用方从ConvertToText(obj)变成obj.ToText()语义没变底层实现彻底换掉了。4.2 手写一个最简单的类型映射源生成器完整实现分三块特性、生成器、消费者项目配置。先定义特性namespace NtlsDemo; [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)] public sealed class MapToTextAttribute : Attribute { }然后写生成器主体。生成器遍历目标类型的所有公共属性把每一行断言式地写进生成代码private static string BuildText(INamedTypeSymbol type) { var props type.GetMembers() .OfTypeIPropertySymbol() .Where(p p.DeclaredAccessibility Accessibility.Public) .ToList(); var body new StringBuilder(); foreach (var prop in props) { body.Append( sb.Append(\).Append(prop.Name).Append(\);).AppendLine(); body.Append( sb.Append(value.).Append(prop.Name).Append();).AppendLine(); } return $$ // auto-generated/ using System.Text; namespace {{type.ContainingNamespace}} { public static partial class {{type.Name}}Extensions { public static string ToText(this {{type.ContainingNamespace}}.{{type.Name}} value) { var sb new StringBuilder(); {{body}} return sb.ToString(); } } } ; }消费者项目里按下面的方式引用生成器ItemGroup ProjectReference Include..\MapToTextGenerator\MapToTextGenerator.csproj OutputItemTypeAnalyzer ReferenceOutputAssemblyfalse / /ItemGroup接着在目标类上打特性[MapToText] public partial class Person { public string? Name { get; set; } public int Age { get; set; } }最后直接person.ToText()。整个过程完全不需要反射。发布时用dotnet publish -c Release -r linux-x64 -p:PublishAottrue产物是原生可执行文件裁剪倒是可以不用单独开了因为 AOT 发布默认会启动裁剪分析而且源生成代码让分析过程顺畅得多。4.3 集成时的陷阱partial、命名空间与调试这类生成器集成有些坑先说最容易踩的。第一partial关键字必须写。生成代码要往同一个类型里合并原类型不写partial就会报已有定义的编译错误。我见过不少同事第一次跑生成器项目时卡在这。第二生成代码要用type.ContainingNamespace而不是写死命名空间。如果消费方项目启用了文件级命名空间或全局命名空间写死的命名空间会让生成代码编不过。让生成器用符号里的ContainingNamespace拼出来基本能覆盖绝大多数情况。第三生成器挂在编译管线里调试难度比普通代码高一点。建议在消费项目里打开两个属性PropertyGroup EmitCompilerGeneratedFilestrue/EmitCompilerGeneratedFiles CompilerGeneratedFilesOutputPathgenerated/CompilerGeneratedFilesOutputPath /PropertyGroup这样每次编译后生成器产出的.g.cs文件都会落到磁盘上。排查生成的东西怎么不对时直接看文件比在生成器代码里打断点快得多。这也是我个人强烈推荐的做法。第四如果生成器报错了不要用throw要在生成器里产出Diagnostic。生成器抛异常会导致整个编译崩溃而且错误信息不友好。用诊断的方式IDE 里还能像普通编译错误一样提示维护起来省心很多。5. 发布配置与验证让 AOT 产物真正可控5.1 关键配置项与裁剪根很多朋友对 AOT 的第一反应是在 csproj 里加一个属性然后 publish。没错基本流程确实就这一步但可观测性不是靠一个属性就能保证的。我把常用配置整理成了一张表方便对照配置项作用建议PublishAot启用 Native AOT 编译最终交付时开启PublishTrimmed启用裁剪AOT 会自动开启单独排查时也可先只开它TrimMode裁剪激进程度partial或full默认partial更稳full体积更小但警告更多TrimmerRootAssembly强制保留某个程序集对动态加载的插件程序集使用TrimmerRootDescriptor用 XML 描述需要保留的类型/成员有具体反射名单时使用IsAotCompatible库项目声明支持 AOT并开启对应分析给类库做兼容性声明的入口SuppressTrimAnalysisWarnings是否屏蔽裁剪警告永远不要设成true裁剪根 XML 的写法也很固定比如某个配置程序集里有一个运行时要反射创建的类型linker assembly fullnameConfigLib type fullnameConfigLib.PluginRegistry preserveall / /assembly /linker然后在 csproj 里把它挂上ItemGroup TrimmerRootDescriptor Includeroots.xml / /ItemGroup这里的原则是能用源生成器解决的不要用 XML 根去硬保必须硬保的越小越好。根越多裁剪效果越差AOT 产物越大。我见过有人图省事把整个程序集preserveall等于绕过了裁剪那还不如不开。5.2 把警告当错误对待用注解传播风险AOT 发布时编译器会打出两类高危警告一类是RequiresUnreferencedCode触发的一类是RequiresDynamicCode触发的。前者表示这段代码依赖元数据裁剪会出问题后者表示这段代码依赖动态代码生成AOT 下会出问题。自己的公开 API 如果包含这类操作一定要主动打上注解而不是等使用者踩坑。比如[RequiresDynamicCode(通过类型名创建实例AOT 下无法保证可用)] public static object CreateByTypeName(string typeName) { return Activator.CreateInstance(Type.GetType(typeName)!); }这样谁调用这个 API谁就会在编译期看到警告然后他才有机会用源生成器或裁剪根去规避。注解的本质是把运行时风险转成编译期可定位风险这对 NTLs 来说特别重要因为风险前置才是这套组合的最终目的。我还会在关键项目里直接把 IL 相关警告提升为错误PropertyGroup WarningsAsErrorsIL2026;IL2057;IL2075;IL2080/WarningsAsErrors /PropertyGroup虽然过程会有点疼但比起让用户在运行时看到MissingMethodException编译时报错显然是更好的选择。5.3 实测数据与验证流程NTLs 到底带来多少收益我拿一个内部模拟项目 X 做了对比。它是个中等规模的控制台工具带少量网络和序列化逻辑。三组发布配置的测试结果大致如下配置体积冷启动时间峰值内存自包含单文件约 65 MB约 180 ms约 80 MB裁剪后自包含约 22 MB约 120 ms约 60 MBNative AOT约 18 MB约 15 ms约 35 MB数据会随着项目规模浮动但趋势是一致的AOT 在启动时间和内存上优势明显体积在单文件场景下也有收益。当然不是所有项目都该无脑 AOT。带大量动态反射、第三方库未适配、依赖特定运行时特性的项目改造成本可能高于收益。验证流程我一般是三步走先在干净的虚拟机或容器里跑一遍可执行文件确认没有外部运行时依赖再把所有业务分支走一遍特别关注序列化、配置加载、插件创建这几个高危点最后用time统计冷启动时间对比基线。别只看能启动就算完事高危分支都要实际触发到。6. 必须接受的代价与几个最容易忽略的坑6.1 AOT 不是免费午餐平台限制与功能收敛第一个代价是平台相关。Native AOT 的发布目标受限于运行时支持的平台组合不能在任意机器上随意交叉编译。跨平台发布时要提前确认目标 RID 是否支持并在目标平台上做验收测试。有些项目涉及平台原生库依赖还需要额外处理链接配置。第二个代价是功能收敛。凡是依赖运行时加载托管程序集的能力在 AOT 下基本都不存在。插件、模块化、动态扩展这类设计要么改成编译期静态注册要么直接换架构。强反射的通用序列化器、ORM 的延迟加载代理也要仔细核对所依赖的库版本是否提供了 AOT 兼容路径。第三个代价是构建时间。AOT 编译比普通编译慢得多因为它要做完整的静态分析和本机代码生成大项目的发布构建时间可能从几十秒变成几分钟。所以本地开发时不要开 AOT只在发布流水线里开配合缓存能缓解一部分成本。我一般会先把PublishTrimmed和分析器警告清干净最后才开 AOT这样能把编译错误提前暴露避免每轮都烧几分钟在构建上。6.2 反射式类库的兼容清单做类库的朋友要尤其认真因为调用你的库的人一旦开 AOT你代码里的反射习惯就会被成倍放大。我自己整理了一份兼容清单每次按它过一遍类型查找禁止用字符串拼类型名尽量用typeof直接引用确实需要运行时再决定的必须暴露RequiresUnreferencedCode注解。实例创建不要到处写Activator.CreateInstance(obj.GetType())改成源生成工厂、委托注入或者泛型约束。属性读取不要用PropertyInfo.GetValue改用生成强类型访问器或者在接口里定义统一访问方法。程序集加载不要运行时扫描目录加载程序集AOT 产物没有这个能力要么静态注册要么进程外插件。序列化优先选用带源生成模式的序列化库并在库内提供partial上下文类让使用方声明所需类型。对照下来大部分老库存活的唯一出路就是把运行时反射替换成编译期生成。这也是为什么这两年很多库的作者都在做这类迁移本质上是整个生态在为 AOT 铺路。6.3 快速判断能不能 AOT的检查单最后分享一个我实际用来评估项目的快速检查单不需要展开代码审查几分钟就能形成判断。搜索源码里的Type.GetType(、Assembly.Load、Activator.CreateInstance(、PropertyInfo.GetValue(看一下出现频率和调用链。频率越高AOT 改造成本越高。跑一次dotnet publish -c Release -r rid -p:PublishAottrue盯着输出里的IL警告条数。数量超过两位数说明还有一堆动态路径没处理。检查核心依赖库的版本说明看它们是否声明了 AOT 兼容或自带源生成器。没有的先升级或替换。确认产品里没有运行时下载新托管程序集这类需求。有的话AOT 这条路基本要绕道。最后才是看收益启动时间、内存、体积是否有硬指标要求。收益不明显就没必要为 AOT 付出迁移成本。这套清单不能代替完整的兼容测试但能帮你在动手前快速判断值不值得投入。我在实际使用中的体会是NTLs 不是必须全盘切换的技术它更像一条风险前置的工程纪律把编译期能确定的事情做扎实把运行时的不确定性尽量赶走。只要方向对了哪怕只是先改掉几处强反射后续再跑 AOT 的路也会顺畅很多。最后再留一个小技巧无论你的项目最终是否启用 AOT都可以把EmitCompilerGeneratedFiles打开定期看看生成器到底生成了什么。很多诡异问题的答案就藏在那些.g.cs文件里。