做 .NET 开发这么多年，我早就不指望dotnet publish跑完就能拿到一个“干净”的发布产物了。每次变更 SDK 版本、调整 NuGet 包、甚至改一个 csproj 属性，都可能让整条构建链重新走一遍——本地还好，到了 CI 上就是十几分钟的等待，再叠加多环境产物差异、容器镜像上下文混乱这类问题，构建发布这件事，始终是团队里最容易互相甩锅的环节。所以当我看到“再次革新 .NET 的构建和发布方式”这个系列的主题，尤其是第三篇引入的“朗”这套方案，我第一反应是：终于有人把构建发布当成一个正经的工程问题来设计了。
这篇博文要讲的就是“朗”这个构建发布方案。它不是又一个包装过的dotnet publish脚本，而是一套从输入指纹、增量缓存到多目标产物生成都重新设计的构建编排思路。简而言之，它解决的是 .NET 项目在持续集成与交付场景下普遍存在的构建慢、缓存命中难、跨平台产物不一致三大痛点。适合正在维护中大型 .NET 解决方案、被 CI 构建时间折磨过、或者想系统化梳理构建发布流程的开发者参考。
1. 项目缘起：为什么构建发布还需要“再次革新”
1.1 传统构建流程的三个老大难问题
先说第一个问题：全量重建。只要有一个文件变动，MSBuild 虽然能检测大部分输入变化，但“检测”本身是保守的——它处理不了诸如环境变量变化、SDK 补丁升级、甚至操作系统区域设置这类隐式输入。结果是 CI 上每次构建都接近全量编译，本地 5 分钟能完成的事情，CI 上跑 25 分钟是常态。
第二个问题叫“缓存失忆”。绝大多数 .NET 项目没有真正跨机器复用的构建缓存，本地obj目录里的中间文件根本不能搬到 CI 上共用。就算打通了 CI，不同拉取请求之间也会因为引用了不同版本的 NuGet 包，导致同样的源码片段被反复编译多次。这种浪费在微服务架构里尤其明显——十几个服务共享同一套类库，每个服务构建时都重新编译一遍公共代码。
第三个问题是“产物漂移”。开发者在 Windows 上跑出的 Self-Contained 发布包，和 CI 上 Linux 容器里跑出的产物，很可能存在行为差异。为什么？因为构建过程隐式依赖了宿主机器上安装的 SDK 补丁级别、全局工具链、甚至环境变量。你很难在事后回答“线上这个二进制到底是哪次提交、哪份依赖清单、哪个 SDK 版本产出的”。
1.2 前两代方案的经验教训
这个系列的前两篇，一篇讲的是“脚本编排时代”，本质就是把一堆dotnet restore/build/publish命令串成 shell 脚本或批处理脚本；另一篇讲的是“容器多阶段构建时代”，利用 Docker 的分层缓存来加速镜像输出。这两代方案都有价值，但都没有真正解决“输入指纹”这个根因。
脚本编排的问题在于：脚本本身就是不可复现的。换一台机器，脚本还能跑，但跑出来的东西可能不一样；多阶段构建解决了“镜像层缓存”的局部问题，可缓存粒度太粗——任何文件改动都会导致后续层全部重建，而且它只能管容器镜像，管不了 Windows 原生产物或 NuGet 包输出。
“朗”这个方案的切入点，就是在容器多阶段构建之上，引入了一层更细粒度的“构建动作缓存”。它把一次 .NET 构建拆成若干个可独立缓存的动作，每个动作的输入都经过标准化指纹计算。命中缓存的动作直接复用产物，未命中的动作才真正执行编译。这套设计让我想起 Bazel 的 action cache，但它没有引入完整 Bazel 的复杂度，而是利用 .NET SDK 自带的增量编译能力 + 声明式配置，做到了足够工程化的落地。
1.3 为什么这次必须改变
微服务拆得越多，构建发布这件事就越像一条流水线，而流水线的效率取决于最慢的瓶颈工序。如果每次代码提交都要把公共类库、基础设施代码、业务服务全部重编一遍，那无论功能开发多快，交付节奏都会被构建拖死。
另一方面，.NET 8/9 引入了大量编译期特性，比如源生成器、NativeAOT、裁剪（Trimming），这些特性的成熟让“发布方式”本身变成了一种架构决策。你不再只是决定“要不要 self-contained”，而是要考虑 AOT 是否适合当前服务、源生成器产生的代码会不会被裁剪掉、单文件发布对动态加载程序集是否有影响。构建发布系统必须能把这些决策显式地表达出来，并固化到可复用的配置里，而不是靠每个开发者在命令行里临时拼参数。
2. “朗”的核心思路：把构建当成一条可复用的流水线
2.1 四层管道：源码快照、依赖图、编译元数据、产物目录
“朗”把一次完整的发布过程拆成四层，每一层都有自己的缓存键和产物：
- 源码快照层：收集项目文件、源代码文件、资源文件的内容哈希。这一层的变化最小，任何文件变动都会在这里体现。
- 依赖图快照层：锁定 NuGet 包版本、SDK 版本、全局工具版本。这一层解决“换了台机器结果就不一样”的问题。
- 编译元数据层：记录 MSBuild 属性、目标框架、Runtime Identifier、DefineConstants 等编译期开关。这一层决定了中间产物（obj）是否可复用。
- 产物目录层：负责输出最终可发布内容，包括二进制、静态资源、容器镜像清单，并打上唯一版本标签。
四层之间是严格依赖关系：上层指纹变了，下层必须重建；但下层的某个文件内容就算发生非语义变化（比如无意义的空行），只要不影响编译，系统也可以选择仅在产物目录层做记录，而不是触发整条重编。这种分层粒度，就是它与传统dotnet build在“增量判定”上的关键区别。
2.2 声明式配置与源生成器的组合设计
“朗”没有发明一套云里雾里的 DSL，它用的是声明式 JSON 配置 + .NET 源生成器来生成 MSBuild 工程。配置里写清楚“要为哪些目标框架发布”“要不要做 NativeAOT”“缓存根目录放在哪”，系统会据此生成一个隐式的.lang/辅助工程，把自定义的构建动作以 MSBuild Target 的形式注入进去。
为什么选这种组合？因为 NativeAOT、单文件、裁剪这些功能，本质上都是 MSBuild 里的一组属性组合。把它们固化成配置项以后，开发者不需要去记PublishSingleFile、PublishTrimmed、PublishAot这些开关之间的关系，也不需要关心它们与 Release 配置的优先级问题。源生成器负责把配置翻译成 MSBuild 属性注入代码，同时还能生成一份BuildManifest.json，记录本次构建用到的 SDK 版本、依赖树、各个文件的指纹。
项目文件里最隐蔽的坑，就是某些全局属性会在“项目重新加载”后被隐式重置。用源生成器把配置写死在辅助工程里，可以避免开发者本地 IDE 与 CI 命令行之间存在属性状态不一致。
2.3 与常见方案的对比
| 方案 | 缓存粒度 | 跨平台一致性 | 学习成本 | 适合场景 |
|---|---|---|---|---|
| 脚本编排 | 无 | 低 | 低 | 原型、简单项目 |
| 容器多阶段 | 镜像层 | 中 | 中 | 纯容器发布 |
| Nuke 等工具 | 任务级 | 中 | 中高 | 复杂流水线定制 |
| “朗”方案 | 动作级 | 高 | 中 | 中大型解决方案、多产物 |
从表格里能看到，它不是要取代所有方案，而是在“需要频繁发布多种形态产物、且对构建时间敏感”的场景里更贴合。如果你只是单项目、单目标框架、本地跑一下就行，那用“朗”确实属于杀鸡用牛刀。
3. 实操落地：用“朗”搭建一套多目标发布管道
3.1 初始化：安装 CLI 工具与创建配置文件
“朗”以 .NET CLI 工具的形式分发，安装方式很简单：
dotnet tool install -g Lang.Cli在解决方案根目录执行：
dotnet lang init这个命令会扫描当前目录下所有*.sln、*.csproj，生成一份默认的lang.init.json。第一次生成的配置长这样：
{ "solution": "src/MyApp.sln", "outputRoot": "artifacts", "targets": [ { "name": "win-x64", "rid": "win-x64", "framework": "net9.0", "selfContained": true }, { "name": "linux-x64", "rid": "linux-x64", "framework": "net9.0", "selfContained": false } ], "cache": { "enabled": true, "root": "/build/cache", "maxAgeDays": 7 } }注意这里缓存根目录我直接指向了/build/cache，而不是本地obj。原因是这套方案默认面向 CI 多机环境，缓存目录会被挂载成共享卷。如果只是本地测试，也可以改成.lang/cache，但效果会打折。
3.2 增量缓存命中与指纹计算的设置
“朗”的增量构建关键在“内容指纹”的计算。它对每个参与编译的.cs文件、.resx资源、xaml等，取其内容的 SHA-256 值；对 csproj 文件则不仅要看内容，还要看它条件引用的属性表。最终形成一个“构建动作的输入指纹集合”，在真正执行编译前，先到这个集合里找缓存。
这里有几个决定命中率的参数，值得认真设：
- SDK 版本必须 pin。如果机器上同时装了 .NET 8 和 .NET 9，而
global.json没有固定版本，同一份源码在不同机器上可能用不同 SDK 构建——指纹永远不一致，缓存也就永远失效。所以务必要提交一个global.json，指定"rollForward": "latestPatch"以及明确的"version": "9.0.x"。 - NuGet 包引用建议开启中央包管理（Central Package Management），并启用
RestoreLockedMode。锁定版本后，依赖图指纹是稳定的，不会因为PackageReference版本解析策略的微小差异导致缓存失效。 - CI 机器的相对路径必须统一。缓存的中间产物里存储了绝对路径信息，如果两台机器的工件目录不一致，命中的概率会急剧下降。“朗”在指纹计算时会把源码路径归一化为相对路径再做哈希，因此要求所有任务必须在同一个根路径下挂载工件。
3.3 一条流水线同时产出 Windows、Linux、容器镜像
“朗”最有说服力的场景，是同一份代码在同一套配置下产出多个目标产物。原理上是依次执行多个发布动作，但缓存系统会识别出不同 target 之间的共享编译单元——比如编译 App.Core 项目这个动作，在win-x64和linux-x64两个 target 下如果是相同的（RID 不影响源码层面的编译），就只编译一次，产物被两个 target 复用。
实际命令长这样：
dotnet lang restore dotnet lang build --target win-x64 --cache dotnet lang publish --target linux-x64 --cache dotnet lang publish --target linux-x64 --container registry.example.local/app:latest我建议把restore单独拎出来，因为 NuGet 还原几乎没有并行安全问题，而且一次 restore 之后，后续所有 target 的还原缓存都能复用。如果跳过这一步，每个 target 都会尝试做一次还原，白白增加几十秒到几分钟的等待。
容器镜像发布这里多说一句。--container会走 .NET 8+ 自带的容器发布能力，生成 OCI 镜像，但“朗”会额外做一件事：它在镜像中注入一份BUILDINFO文件，记录源码提交号、构建时间戳、SDK 版本。日后排查线上问题时，直接在容器里读取这份文件，就能还原出“这镜像是怎么来的”。这个细节我强烈建议所有团队都加上，它省下的排查时间远比多花的那几字节存储要多。
3.4 与现有 CI 流程集成
不管团队用哪种 CI 平台，本质都是三件事：拉取代码、执行构建命令、归档产物。“朗”的命令设计对 CI 很友好，因为它不需要交互式终端，退出状态码准确反映构建成败。我常用的 CI 步骤模板是这样：
- restore: dotnet lang restore - build: dotnet lang build --target linux-x64 --cache - publish: dotnet lang publish --target linux-x64 --cache - archive: - artifacts/linux-x64/ - .lang/BuildManifest.json关键是把.lang/BuildManifest.json当作构建产物的一部分归档。这份清单里记录了每一个输入文件的哈希、每个构建动作的缓存命中状态、所用工具链版本。如果 CI 上出现“我本地能跑但 CI 不行”的经典问题，先从这份清单开始比对，比直接去翻日志高效得多。
我这里特别想强调一个 CI 上的细节：不要在临时目录里构建。很多 CI 平台默认在$(build.sourcesDirectory)或/tmp/xxx里跑，这类路径可能随机变化。“朗”的共享缓存依赖固定根路径，如果每次构建都在全新目录，缓存命中率基本归零。正确的做法是在所有构建机上把缓存目录和源码目录都固定在同一个抽象路径下挂载，比如都从/workspace开始。
4. 常见问题与排查技巧实录
4.1 缓存命中率低：先查指纹而不是先查日志
缓存命中率低是最常见的“性能事故”。我在一个服务众多、结构复杂的解决方案上，曾经把命中率从 60% 提到 92%，核心就是定位“哪些指纹其实不该变结果却变了”。先跑一条命令查看明细：
dotnet lang cache explain --target linux-x64它会列出每个构建动作的输入指纹，并标出与上次命中时相比哪些指纹发生了变化。最常见的三个元凶：
- SDK 补丁版本悄悄变化。
global.json里写了9.0.100，但 CI 机器实际安装了9.0.103，某些 MSBuild 属性输出会带 SDK 版本号，导致指纹变化。解决方法是把具体补丁版本写死，或者统一用同一版本的 SDK 镜像。 - 环境变量参与编译。比如有项目读取
CI、BUILD_NUMBER等变量去生成版本号，这些变量一旦进入 MSBuild 属性，就会引起下游动作指纹变化。建议在配置里显式声明“哪些环境变量参与指纹计算”，其他变量一律忽略。 - 生成的文件没有排除在外。不少解决方案会在构建时动态生成
AssemblyInfo.cs或版本文件，如果这些文件被当作普通源码参与哈希，就会造成“构建一次变一次”的死循环。需要把临时生成目录加入lang.init.json的ignorePatterns。
4.2 源生成器与 NativeAOT 冲突怎么处理
这个坑我踩得比较深。有一个公共基础类库用了源生成器来生成依赖注入注册代码，听起来挺美，本地跑通，CI 上用--aot发布后在运行期死活报找不到类型。根源在于：源生成器生成的代码默认是普通引用，而 NativeAOT 会进行裁剪，编译器无法静态分析源生成器到底产生了哪些类型，于是把注册代码当没有引用剪掉了。
“朗”提供的思路是：在配置里声明“这个项目的源生成器输出需要保留元数据”。它会在发布时自动给对应项目加上：
<PropertyGroup> <PublishAot>true</PublishAot> <TrimmerRootDescriptor>$(MSBuildProjectDirectory)/TrimmerRoots.xml</TrimmerRootDescriptor> </PropertyGroup>而TrimmerRoots.xml里列出需要保留的程序集：
<linker> <assembly fullname="MyApp.Generated" preserve="all" /> </linker>问题不在于这个配置文件怎么写，而是你要意识到：源生成器 + 裁剪 + AOT 这三件事组合起来时，任何“动态发现类型”的行为都要被显式声明。不要指望编译器自动变聪明，它不会。
4.3 跨平台路径与权限问题速查
| 现象 | 可能原因 | 快速解决办法 |
|---|---|---|
| Windows 下构建产物在 Linux 容器中不可执行 | 没有设置 Executable 权限位 | 在配置中开启setExecutableBit: true |
| 路径过长导致 NSBuild 报错 | Windows MAX_PATH 限制 | 启用系统长路径支持，或设置outputRoot为短路径 |
/build/cache提示 Permission denied | 容器内非 root 用户无权限 | 在 CI 步骤中mkdir -p /build/cache && chown |
| 构建时间戳与源码提交时间不符 | 时区不同 | 统一在 CI 配置中设置TZ=UTC |
这些看起来是“小问题”，但在多平台同时构建时，任何一个都会让整条流水线红掉。我的经验是：越早把所有构建机的“时间、语言、区域、权限基线”统一，后面能省的沟通成本越多。
4.4 产物可复现性检查
“朗”内置了一个可复现性验证动作——验证同一份源码、同一份配置、同一个缓存目录下，两次完整发布得到的二进制是否完全一致。实际操作中，我发现一个常见变数：第三方依赖里可能带有Deterministic属性为 false 的旧库，导致生成的 PDB 或程序集包含生成时间戳，破坏一致性。
排查手段是通过构建清单对比两次构建的相关指纹，锁定是哪个项目在哪个动作上出现了非确定性。通常解决方案是给 csproj 统一加上：
<PropertyGroup> <Deterministic>true</Deterministic> <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild> </PropertyGroup>ContinuousIntegrationBuild这个属性我尤其要提一下，它会让编译器去掉本地调试相关的路径信息。很多团队没有开它，导致本地构建与 CI 构建的可执行文件体积不一样，即使代码完全一致。开启之后，产物一致性检查会稳定很多。
5. 最后的实操心得
如果只让我分享一条经验，那就是：不要一上来就追求“全量共享缓存”，先把指纹计算和构建清单跑通，再逐步放开缓存目录。我一开始在团队里推行时，直接把 CI 机器的缓存目录挂到共享存储上，结果因为不同分支的 SDK 版本差异，导致缓存互相污染，构建时偶尔出现脏产物。后来改为“每个发布目标独立缓存分区 + 指纹失效即弃用”，才算彻底稳定下来。
另一条心得和团队协作有关：构建发布方式的变革，一定要让开发者能在本地重复 CI 的命令。如果一个方案只存在于 CI 配置里，本地复现不了，那么开发迭代节奏会变成“改代码 -> push -> 等 CI 报错”，效率极低。“朗”的好处是命令统一，本地dotnet lang build --target linux-x64 --cache与 CI 上完全一致，谁都可以在自己机器上复现 CI 的构建动作。这才是构建发布系统真正值得花时间投入的方向——让每一次构建都可解释、可复现、可复用，而不是让构建变成黑盒。从实际效果看，这套方案让我所在团队的 CI 平均构建时长压缩了接近一半，而且跨平台产物不一致的问题基本绝迹。如果你们团队也在被这类问题困扰，不妨从一份lang.init.json开始试验。
