C# Academy · 课时

原生 AOT 编译

Q: 「原生 AOT 编译」这节课中我会学到什么？

在 .NET 项目中启用原生 AOT，了解裁剪分析，并发布自包含的原生二进制文件。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在 .NET 项目中启用原生 AOT，了解裁剪分析，并发布自包含的原生二进制文件。

原生 AOT 编译 是 CoddyKit 上的免费 C# Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

什么是原生 AOT？

原生提前编译（AOT）会在发布时将 .NET 应用编译为自包含的原生二进制文件。目标环境不需要 JIT 编译器，也不需要 .NET 运行时——只需一个可执行文件即可。

何时使用原生 AOT

对于微服务、CLI 工具和无服务器函数，原生 AOT 在启动时间和内存占用方面表现出色。但对于严重依赖运行时反射的应用，它并不理想。

// Ideal use cases:
// - Serverless functions (AWS Lambda, Azure Functions)
// - High-throughput microservices (fast cold start)
// - CLI tools shipped as single-file executables
// - IoT / embedded scenarios

// Poor fit:
// - Apps using extensive reflection (e.g., dynamic proxies)
// - Apps loading plugins at runtime
// - Apps depending on libraries that don't support trimming

// Key benefits:
// - Sub-10ms startup time (vs 200-500ms for JIT)
// - Lower memory at startup (no JIT overhead)
// - Smaller attack surface (no JIT engine)

使用原生 AOT 发布

在项目文件中启用 AOT，然后使用 dotnet publish 发布。输出是一个不依赖运行时的单一原生可执行文件。

// .csproj:
<PropertyGroup>
  <PublishAot>true</PublishAot>
  <!-- Optional: disable invariant globalization for smaller binary -->
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

// Publish for Linux x64:
dotnet publish -r linux-x64 -c Release

// Publish for Windows x64:
dotnet publish -r win-x64 -c Release

// Output: bin/Release/net9.0/linux-x64/publish/MyApp
// Single executable, no dotnet runtime required

使用原生 AOT 的最小 API

ASP.NET Core Minimal APIs 从 .NET 8+ 开始完全支持原生 AOT。请使用 dotnet new webapiaot 模板作为预配置的起点。

// dotnet new webapiaot -n FastApi

// Program.cs generated template:
var builder = WebApplication.CreateSlimBuilder(args); // AOT-optimized

// Must register serialization context for AOT:
builder.Services.ConfigureHttpJsonOptions(opts =>
    opts.SerializerOptions.TypeInfoResolverChain.Insert(0,
        AppJsonSerializerContext.Default));

var app = builder.Build();
app.MapGet("/hello", () => new Message("Hello, Native AOT!"));
app.Run();

record Message(string Text);

[JsonSerializable(typeof(Message))]
internal partial class AppJsonSerializerContext : JsonSerializerContext { }

源代码生成的 JSON 序列化

Native AOT 无法使用基于反射的 JSON 序列化。您必须使用 System.Text.Json 源代码生成，在编译时生成序列化代码。

// Define types to serialize:
public record Product(int Id, string Name, decimal Price);
public record OrderDto(int OrderId, List<Product> Items);

// Create a JsonSerializerContext for AOT:
[JsonSerializable(typeof(Product))]
[JsonSerializable(typeof(OrderDto))]
[JsonSerializable(typeof(List<Product>))]
internal partial class MyJsonContext : JsonSerializerContext { }

// Serialize / deserialize without reflection:
var json = JsonSerializer.Serialize(product, MyJsonContext.Default.Product);
var product = JsonSerializer.Deserialize(json, MyJsonContext.Default.Product);

裁剪警告

使用 Native AOT 发布时，默认会启用裁剪。编译器检测到移除未使用代码后可能导致失败的代码时，会发出警告。在持续集成期间将裁剪警告视为错误。

// .csproj: treat warnings as errors in CI
<PropertyGroup>
  <PublishAot>true</PublishAot>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <TrimmerRootDescriptor>TrimmerRoots.xml</TrimmerRootDescriptor>
</PropertyGroup>

// Suppressing a specific warning when you know it is safe:
[DynamicDependency(DynamicallyAccessedMemberTypes.All, typeof(MyClass))]
public static void EnsureMyClassSurvivesTrimming() { }

// Or annotate parameters:
public static void Register(
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
    Type serviceType) { }

AOT 兼容性分析器

在开发期间运行 AOT 兼容性分析器，以便在不兼容的代码路径演变为发布时错误之前发现它们。

// Enable analysis without actually publishing AOT:
<PropertyGroup>
  <EnableAotAnalyzer>true</EnableAotAnalyzer>
  <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
  <EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
</PropertyGroup>

// Run:
// dotnet build
// => analyzer reports issues in build output

// Common warnings:
// IL2026: member uses RequiresUnreferencedCode
// IL2046: member annotated with RequiresUnreferencedCode derives from unannotated
// IL3050: member uses RequiresDynamicCode

启动性能比较

与使用 JIT 编译的应用相比，Native AOT 能大幅缩短启动时间并降低内存使用量。代价是，对于某些工作负载，发布时间更长且可执行文件更大。

// Typical Minimal API measurements:
// JIT (.NET 9, linux-x64):
//   Startup time:  ~180ms
//   Memory (RSS):  ~60 MB
//   Publish time:  ~5s
//   Executable:    self-contained ~80 MB

// Native AOT (.NET 9, linux-x64):
//   Startup time:  ~5ms   (36x faster)
//   Memory (RSS):  ~20 MB (3x less)
//   Publish time:  ~30s   (6x slower to build)
//   Executable:    ~10 MB (8x smaller)

// For AWS Lambda / Azure Container Apps:
// AOT cold start: <10ms vs JIT: 300-500ms = significant billing savings

实战：使用 AOT 的 Lambda 函数

一个使用官方 Amazon.Lambda.RuntimeSupport 包的 Native AOT Lambda 函数，可实现最佳冷启动性能。

// dotnet new lambda.NativeAOT

// .csproj:
// <PublishAot>true</PublishAot>
// <StripSymbols>true</StripSymbols>

public class Function
{
    [JsonSerializable(typeof(APIGatewayProxyRequest))]
    [JsonSerializable(typeof(APIGatewayProxyResponse))]
    internal partial class LambdaContext : JsonSerializerContext { }

    static async Task Main()
    {
        Func<APIGatewayProxyRequest, ILambdaContext, APIGatewayProxyResponse>
            handler = FunctionHandler;

        await LambdaBootstrapBuilder
            .Create(handler, LambdaContext.Default.APIGatewayProxyRequest)
            .Build()
            .RunAsync();
    }

    static APIGatewayProxyResponse FunctionHandler(
        APIGatewayProxyRequest req, ILambdaContext ctx)
        => new() { StatusCode = 200, Body = "{\"status\":\"ok\"}" };
}

快速检查

为什么使用 Native AOT 时，必须使用 System.Text.Json 源代码生成，而不能使用基于反射的序列化？

回顾：Native AOT 编译

要点：

Native AOT 编译为自包含的本机二进制文件——无需运行时
非常适合无服务器应用、微服务和 CLI 工具（启动快、内存占用低）
使用 <PublishAot>true</PublishAot> 启用，并使用 -r <rid> 发布
必须使用 System.Text.Json 源代码生成——基于反射的序列化无法工作
使用 EnableAotAnalyzer 在开发期间发现兼容性问题
权衡：发布时间更长、反射受限，但冷启动速度可提高 5 到 35 倍

常见问题解答

「原生 AOT 编译」课时是免费的吗？

是的 — 「原生 AOT 编译」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「原生 AOT 编译」这节课中我会学到什么？

在 .NET 项目中启用原生 AOT，了解裁剪分析，并发布自包含的原生二进制文件。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「原生 AOT 编译」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy