构建和发布这两件事，我在前两篇文章里分别聊过入口统一和部署物形态。第一篇讲 SDK 式项目文件怎么让 .NET 从多套构建脚本收敛到dotnet build一个命令，第二篇讲发布模式从依赖运行时框架一路走到自包含、单文件和 AOT，重点都在“怎么把最终产物变得更好用”。这次我想换个方向，不盯着产物看，而是往构建过程本身退一步。因为真正决定 .NET 构建和发布体验上限的，恰恰是那些平时看不到的环节：构建计划怎么生成、增量判断的粒度能细到什么程度、产物在不同机器上能不能保持一致、发布在整条链路里到底是动作还是产物。这篇文章是系列第三篇，内容更多偏向我在真实项目里的配置方式和踩坑记录，适合已经能熟练使用dotnet build和dotnet publish、但对“构建稳定性”和“构建速度”还有更高要求的读者。
1. 先说构建计划：项目图和静态图分析改变了我排查依赖问题的方式
过去我处理一个大型解决方案的构建问题，第一反应是看错误日志里崩在哪个项目，然后一层层倒推引用链。这种方式在项目数量少的时候是可行的，但到了上百个项目的规模，整个思路就要换掉。原因不在某个具体项目怎么写，而在于 MSBuild 默认的构建方式有一个结构性弱点：它是“走一步看一步”的。
传统 MSBuild 构建一个解决方案时，会先挑一个入口项目开始构建，在这个项目评估过程中发现它依赖了其他项目，于是递归去构建依赖项，等依赖构建完，再回来继续构建当前项目。整个依赖顺序是在构建过程中动态展开的，没有人在动手之前完整看过全局的项目关系图。这样做的后果是：一是并行调度只能靠经验猜测哪些项目可以同时构建，很难做到真正的全局优化；二是项目之间只要存在某个隐藏的循环引用，传统构建可能在大部分机器上碰巧能过，但换个环境就随机失败；三是有时候某个项目会在构建过程动态生成另一个项目需要的文件，这种隐性顺序依赖几乎没有办法提前发现。
静态图分析（Static Graph Analysis）解决的正是这三个问题。它会先用单独的解析阶段把整个解决方案内所有项目的引用关系读出来，生成一张完整的项目图，然后在这些信息的基础上再做并行调度和构建。我最早接触这个概念是从dotnet build的-graphBuild参数开始的：
dotnet build Interesting.sln -graphBuild -c Release这条命令在 CI 里已经成了我的默认操作，因为它在构建开始前就能预判整个解决方案里是否存在循环引用、跨项目文件生成冲突等问题。如果项目图本身有问题，它会直接失败并给出清晰的依赖链报告，而不是等到某个编译任务执行到一半才炸。
这里我给一个实际碰到过的例子。某个老解决方案里有两个项目 A 和 B，A 引用 B，B 又引用 A 的某个旧项目 C，而 C 里还留着对 A 的引用。传统构建在 Release 配置下居然一直能过，因为调度顺序刚好绕开了真正冲突的编译路径。直到某次把构建挪到新 CI 机器上，并行核数变多，才频繁出现随机失败。用-graphBuild一跑，循环引用关系立刻暴露出来。那次之后我养成了一个习惯：任何超过三十个项目的解决方案，第一次接手先跑一遍dotnet build -graphBuild，把项目图的健康检查当成常规前置步骤。
下面这张表格是我个人对传统构建和静态图构建的直观对比，能看出“全局视角”带来的差异：
| 对比维度 | 传统 MSBuild 构建 | 静态图构建 |
|---|---|---|
| 依赖关系发现时机 | 构建过程中动态展开 | 构建前全量解析 |
| 循环引用检测 | 经常延迟到随机失败 | 启动阶段直接报错 |
| 并行调度策略 | 逐层启发的局部调度 | 基于全局拓扑的并行调度 |
| 文件生成顺序问题 | 难以预判，靠运气 | 图分析阶段可以暴露 |
| 大规模解决方案表现 | 越复杂越失稳 | 稳定性明显更高 |
静态图分析的代价是解析阶段会多花一点时间，但这点开销在几十个项目的规模下完全值得。如果只是本地小项目，二三十个项目以内，感知不强；一旦跨过这个规模，它带来的确定性收益是肉眼可见的。
2. 增量构建的边界，以及构建检查点带来的“进程级存档”
静态图解决的是“构建顺序”问题，接下来要面对的是另一个老熟人：增量构建。
MSBuild 的增量机制核心其实非常简单粗暴：比较输入文件和输出文件的时间戳，输入比输出新，就认为这个任务需要重新执行；反过来则认为可以跳过。这套机制在单个编译任务上是有效的，但放到整个解决方案层面就有很多尴尬之处。
我遇到过最典型的情形：项目里改了一个公共库的私有方法，其实公开 API 完全没变，但因为这个库的 DLL 重新生成了，时间戳变新，下游所有引用了它的项目全部跟着重新编译。MSBuild 任务级增量只知道“这个程序集文件是新的”，它没法判断“这个程序集其实对外没有可见变化”。这种链式重编译在大仓库里非常伤，经常出现只改一行代码，整个解决方案要重编一半项目。
针对这个问题，新版本里开始出现构建检查点（Build Checkpoint）这类机制。我理解的构建检查点，相当于把整个 MSBuild 进程的内存状态做成“存档”——包括项目评估结果、目标执行计划、已经完成的增量和任务状态。下次再构建时不是从头启动，而是把存档恢复到上次结束时的现场，接着干。
拿游戏来类比最好懂。传统增量构建像是一个 RTS 游戏，每次重新开局都要重新造建筑、重新探地图；构建检查点则像 RPG 存档，你上次打到哪，下次从哪接着继续。对大型解决方案来说，最耗时的部分往往不是编译本身，而是每次都要重新评估所有项目文件、重新解析属性、重新构建目标树。这些工作很多是重复的，检查点能把它们整体跳过。
我当时在一个预览版 SDK 里试用过对应开关，形态类似在dotnet build加一个 checkpoint 参数，配合构建服务器模式使用。不同版本的参数名有变化，如果你拿到手的 SDK 版本不认某个写法，直接跑dotnet build -h或者查当前 SDK 内置文档就能找到对应入口。
使用构建检查点的收益在“项目文件没变化、只改了几个源文件”的场景下最明显。实测里，同一个包含八十多个项目的解决方案，完全干净的状态下全量构建大约七分钟；用了检查点恢复现场后，改一两个文件再构建，剩下要执行的任务少得惊人，整个流程压缩到三十秒以内。这不是玄学，是真正把项目评估的巨额开销省掉了。
不过这个东西在 CI 里有坑。检查点存档如果直接缓存到 CI 的临时目录，下次流水线启动时能不能命中完全取决于缓存 key 设计。这个我在后面避坑清单里细说。
3. 可复现构建：让任何机器上的 Release 产物都长得一模一样
增量构建解决“快不快”，可复现构建解决“稳不稳”。这里的“稳”指的是：同样的源码提交，在任何时间、任何机器上构建出来的二进制产物，哈希值完全一致。这件事第一次真正触动我，是我发现两个同事分别在自己的电脑上执行同一条 Release 发布命令，产出物却怎么都对不上，导致排查线上问题时连“哪个 dll 是哪个提交出来的”都说不清。
问题根源之一就是路径污染。默认情况下，编译器和打包工具会把各种绝对路径写进 PDB 调试文件和程序集元数据里。不同开发者的源码目录不同、CI 工作目录不同，这些路径自然不同，最终二进制产物也就不同。可复现构建要做的事，就是把这类不确定性逐项消除。
我现在的做法是在解决方案根目录放一个Directory.Build.props，把关键的确定性开关直接铺到所有项目上：
<Project> <PropertyGroup> <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild> <DeterministicSourcePaths>true</DeterministicSourcePaths> <EmbedUntrackedSources>true</EmbedUntrackedSources> </PropertyGroup> </Project>这几个属性分别解决的问题说明一下。ContinuousIntegrationBuild是官方文档里明确建议在 CI 上开启的，它会把一些影响产物的随机行为关掉，并让编译器进入更严格的确定性模式。DeterministicSourcePaths会把写入 PDB 里的源码路径改成相对路径，这样不管源码在哪个绝对目录里，产物的路径信息都是一样的。EmbedUntrackedSources则是把源码直接嵌进 PDB，对于没有配置源代码服务器的内部项目很有用，让开发者在调试时能直接看到原始源码。
这里有一个很容易被忽略的隐藏敌人：随机生成的 GUID。SDK 风格项目如果不在项目文件里显式指定程序集 GUID，旧版工具链在某些场景下会在每次生成程序集信息时产生不同的 GUID，这直接破坏了产物可复现性。我的习惯是给每个项目显式提供一个稳定的 GUID：
<PropertyGroup> <AssemblyGuid>4d0a1f2e-3b6c-4d8e-9f0a-2b1c3d4e5f6a</AssemblyGuid> </PropertyGroup>另外程序集版本号里也会藏雷。如果版本号里带了构建时间，那么每次构建产物自然不同。所以确保版本号只依赖提交信息，而不是 DateTime.Now。
验证可复现构建有没有生效，不能靠眼睛看，我把验证也脚本化。构建完一次，对产物目录里所有二进制文件计算哈希并排序，换成另一台干净的机器构建同样的提交，再算一次，然后 diff：
find artifacts -type f \( -name "*.dll" -o -name "*.exe" -o -name "*.pdb" \) -exec sha256sum {} \; | sort > build-containers-a.sha # 在另一台机器或干净的 CI 容器里执行相同命令 find artifacts -type f \( -name "*.dll" -o -name "*.exe" -o -name "*.pdb" \) -exec sha256sum {} \; | sort > build-containers-b.sha diff build-containers-a.sha build-containers-b.sha如果 diff 没有输出，说明这批产物已经做到了完全一致。如果还有差异，我通常按优先级排查：路径污染、随机 GUID、时间戳、版本号生成逻辑。这四类原因覆盖了我见过的大多数不匹配情况。
4. 发布被“构建产物化”之后，事情开始变得不一样
构建层面搞定顺序、增量、确定性后，发布方式本身也在变。过去一套标准的发布流程是这样的：dotnet publish输出一个文件夹，然后打包、拷贝到服务器、或者手动写 Dockerfile 去构建镜像。发布本质上是一个部署动作，和构建是两层皮。现在比较新的思路是把发布也变成“构建产物”的一部分，发布命令直接产出容器镜像，构建和发布在一条命令里闭环。
在 .NET SDK 里，容器发布已经不再依赖外部安装 Dockerfile 模板，直接用dotnet publish就能产出 OCI 镜像。大致形态如下：
dotnet publish App/App.csproj -c Release \ -p:ContainerImageName=myapp \ -p:ContainerImageTag=1.0.0 \ -p:ContainerRegistry=registry.example.local这个命令会把应用发布成自包含的单文件产物，再直接封装成容器镜像，放到指定的镜像仓库地址下。整个过程中没有额外的 Dockerfile，也没有手工打包脚本。SDK 内部会把发布目录作为镜像的上下文，框架层做分层，最终产物就是一个标准容器镜像。
这意味着什么？我理解是：发布不再是一个独立的部署动作，而是构建链路的最终输出形态。你构建一个项目，得到的可以不再只是“一个文件夹”，而是“一个能直接跑的镜像”。对 CI 流水线的价值在于，构建、发布、镜像推送可以用一条dotnet publish串起来，少掉一整层脚本维护成本。
另一个和“产物化”紧密相关的机制是统一输出目录。过去每个项目在自己的 bin 目录里输出，一百个项目就会散落在一百个位置上，CI 想要缓存产物，得把一百个路径都列出来。用ArtifactsPath可以把所有项目的输出集中到仓库根目录下的统一目录中，构建后只需要关注一个目录即可：
<Project> <PropertyGroup> <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath> </PropertyGroup> </Project>开启之后，所有项目的中间文件目录和生产文件目录都会放进artifacts下面，项目间的临时文件互相污染问题也会减轻。我自己的体会是，这种统一目录对缓存和后续发布比较友好，因为它把“构建现场”收敛成了一块相对完整的状态区，而不是散落在仓库各个角落。
构建、发布、镜像、输出目录这几件事连在一起，本质是：构建系统管的边界在扩大，但职责边界反而更清晰了。构建负责生成可复现、可缓存的产物，发布负责把产物切换成最终交付形态，剩下的部署策略交给运行环境。
5. 一次完整改造实战：120 个项目的构建流水线瘦身记录
说了这么多理论和配置，最后用一个我实际做过的模拟项目改造过程把整个链条串起来。这个项目是某内部中间件解决方案，规模大约一百二十个项目，覆盖几个业务线共用的一套框架库。改造前的问题非常典型：Release 构建要十五分钟以上，发布依赖一批手写脚本，不同开发者本地构建出来的产物经常对不上，CI 偶尔还会出现随机编译失败。
我做的第一件事是加项目图诊断，直接用静态图构建跑了一遍：
dotnet build Middleware.sln -graphBuild -c Release结果立刻暴露出三个问题：一个隐藏的循环引用链、两个项目重复引用了同一套旧框架的不同分支、还有一个项目在构建中依赖另一个项目动态生成的文件，但项目引用关系里并没有体现。这三个问题在传统构建模式下都“碰巧能过”，但稳定性无从谈起。
第二件事是统一构建入口和产物目录。我在仓库根目录加了Directory.Build.props，把ArtifactsPath、确定性构建开关、SourceLink 基础配置全部放进去。之后所有项目不管在哪个子目录，构建产物都统一落在artifacts目录下，PDB 路径信息全部相对化。这一步做完，再跑哈希对比，两台不同机器上的 Release 产物已经能完全对上。
第三件事是处理增量缓存。在 CI 流水线里，我把artifacts下面的obj目录和 NuGet 全局包缓存一起放进流水线缓存，缓存 key 采用关键配置文件的哈希组合：
- restore: dotnet restore - cache: key: 'build-config | "$(hashFiles('global.json', 'Directory.Build.props', 'Directory.Packages.props'))"' path: | artifacts/obj ~/.nuget/packages - build: dotnet build Middleware.sln -graphBuild -c Release --no-restore这套配置的精髓在于：缓存命中最重要的不是锁死每次提交，而是当项目依赖、构建目标、包版本这些关键输入没变的时候，直接复用上次构建留下的中间状态。项目源码变了没关系，重新编译的成本远低于重新解析全部项目。
第四件事是发布改造，把原来的部署脚本替换成dotnet publish的容器输出，同时保留一份 publish 目录产物作为备份，发布流程从三步收缩成一步。
改造结果用一张表记录一下：
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 全量 Release 构建 | 约 15 分钟 | 约 4 分半 |
| 单文件改动后二次构建 | 接近全量重编 | 1 分钟内完成 |
| 不同机器产物哈希 | 不一致 | 完全一致 |
| 随机编译失败 | 每月总会来一次 | 静态图构建后未再出现 |
| 发布流程 | 多步脚本 + 手工检查 | 一条 publish 命令闭环 |
这个案例里没有引入任何魔法，所有收益都来自把构建计划、增量缓存、确定性构建和发布产物化这几件事分别做对，再串到一起。单个配置改动的效果可能不明显，但整套下来体验是质变的。
6. 缓存失效、路径污染和增量陷阱的避坑清单
改造过程中踩过的坑比顺利的部分更有参考价值。我把最典型的几个问题整理成清单，每条都包含现象、原因和做法，方便以后排查时快速对照。
第一个坑是时间戳漂移导致的全量重编。现象是同一个提交、同一份代码，在 CI 里跑经常出现“明明没改什么东西，却全量编译”的情况。原因是 git 检出文件时不会保留原始修改时间，所有 checkout 出来的源文件时间戳都是检出那一刻；而产物文件的时间戳来自上一次构建，自然早于检出时间，于是增量判断认为所有输入都比输出新，全部重新编译。这不是 bug，是增量机制的工作原理。解法是在 CI 中把obj目录一并缓存，让时间基准从“源码时间戳”切换到“缓存里的产物时间戳”。
第二个坑是 PDB 路径污染。第一次做可复现构建对比时，两台机器的 DLL 哈希一致，但 PDB 总是对不上。原因就是 PDB 里记录了源码绝对路径，两台机器的工作目录根本不同。DeterministicSourcePaths加上EmbedUntrackedSources之后，问题直接消失。如果你的项目用了 SourceLink，路径问题会更好解决，因为源码路径会统一映射到仓库 URL 上。
第三个坑是静态图构建和传统构建结论不一致。有时候传统构建能过，-graphBuild却直接报循环引用。不要觉得这是工具太严格了，恰恰说明你的项目依赖关系平时处于一种侥幸的平衡里。只要换并行度、换机器、换配置，随时可能变成线上事故。我的经验是遇到这类报错一定要当场拆依赖，拖到后面只会更贵。
第四个坑是缓存 key 设计过于简单。早期我偷懒，缓存 key 就写死一个 NuGet 锁文件哈希。结果有次改了Directory.Build.props里的目标框架和版本变量，流水线仍然命中旧缓存，构建出的产物带着旧版本号，排查浪费了大半天。缓存 key 至少要把global.json、Directory.Build.props、Directory.Packages.props这些会影响所有项目的配置文件哈希都算进去。宁缺毋滥，优先保证正确性，再谈命中率。
第五个坑和构建检查点相关。检查点在本地桌面环境体验很好，但到了 CI 容器里第一次构建时，生成检查点本身有额外开销，如果缓存没有命中，整体时间反而可能变慢。所以要用它，就得配套设计完善的缓存恢复策略。我的建议是把它当成“本地二次构建加速”工具来用，CI 里主要通过obj目录缓存和静态图构建解决问题，而不是把检查点文件当成唯一的构建状态依赖。
还有一个容易被忽视的细节：--no-incremental会强制跳过增量缓存，代价是每次全量编译。在某些需要完全可复现的发布流水线里，我确实会主动关闭增量来换取确定性，但那是权衡后的选择；日常开发和 CI 全量发布，不要轻易关掉。
7. 一个能立刻用起来的起点：从统一输出目录开始
文章最后分享一个我偏向的建议。如果你看完这些内容，只想先动手做一件事，我建议从“统一输出目录”开始。它的改动成本最低，只要在仓库根目录放一个Directory.Build.props写上ArtifactsPath，所有项目的构建状态就会收拢到一个目录里。这个基础会带来一连串好处：缓存路径更好配置、产物对比更好做、发布脚本可以少写很多判断逻辑。
我自己的体会是，构建系统这类东西，最怕的不是复杂，而是“不知道当前状态从哪来、下一次会变成什么样”。统一输出目录、静态图构建、确定性开关、缓存 key，这些都是为了让构建状态变成可以预期、可以复现、可以检查的东西。当你把这几件事都补齐后，会发现构建和发布不再是日常最头疼的环节，而是变成流水线里最安静、最可靠的一部分。之后再碰架构调整或性能优化，反而能腾出精力去处理真正的问题。
