企业官网建设流程全解析

MSBuild 增量构建实战：从 binlog 定位"什么都没改却总是重新编译"的 8 大根因

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills

增量构建（Incremental Build）是 MSBuild 最容易被忽视、也最常被"误伤"的性能机制：它让目标（Target）在输出已是最新时被整体跳过，从而大幅缩短后续构建时间。但在真实项目中，"明明什么都没改，构建却照跑不误"几乎每天都在发生。本篇以 incremental-build Skill 为骨架，结合 dotnet-msbuild 插件 中配套的 binlog 生成、binlog 分析、Target 编写等 Skill 与评估用例，系统讲解 MSBuild 增量构建的工作原理、导致增量失效的 8 大根因、基于 binlog 的"为什么又重编了"诊断方法论，以及把自定义 Target 改造成真正增量化的完整实践。读完你将能独立回答"第二次构建到底该不该重编、为什么重编、如何让它不再重编"。

增量构建的工作原理：MSBuild 靠什么决定"跳过"

MSBuild 的增量构建机制允许目标在"输出已是最新"时被跳过，这是后续构建大幅提速的根本来源。它的决策模型非常朴素，完全基于Inputs/Outputs属性与文件时间戳：

• 声明了Inputs和Outputs的目标：MSBuild 会比较Inputs中所有文件的时间戳与Outputs中所有文件的时间戳。如果每个输出文件都比每个输入文件新，该目标就会被整体跳过；
• 没有声明Inputs/Outputs的目标：每次构建调用都会执行。这是默认行为，也是增量构建变慢最常见的原因；
• Incremental属性：目标可以显式选择加入或退出增量行为。Incremental="false"会强制目标每次运行，即使指定了Inputs/Outputs也无效；
• 基于时间戳而非内容哈希：MSBuild 使用文件系统的时间戳（最后写入时间）判断过期与否，不做内容哈希。因此仅仅"触碰"一个文件（更新时间戳而未改内容）就会触发重新构建。

一个典型的增量目标与一个"永远全量执行"的目标对比如下：

<!-- 这个目标是增量的：当 Output 比所有 Input 都新时被跳过 --> <Target Name="Transform" Inputs="@(TransformFiles)" Outputs="@(TransformFiles->'$(OutputPath)%(Filename).out')"> <!-- work here --> </Target> <!-- 这个目标因为没有 Inputs/Outputs 每次都会运行 --> <Target Name="PrintMessage"> <Message Text="This runs every build" /> </Target>

理解这条规则是后续一切诊断的前提：凡是没有Inputs/Outputs的 Target，就不可能被跳过。仓库中 incremental-build 的评估用例 第一条 rubric 正是要求识别"自定义目标缺少 Inputs 和 Outputs 属性"——这是该 Skill 的训练与考核核心。

增量构建失效的 8 大根因

实践中增量构建"悄悄失效"的原因高度集中，本 Skill 归纳为以下 8 类，几乎覆盖了绝大多数真实场景：

1. 自定义 Target 缺少Inputs/Outputs——两个属性缺一，目标就永远执行。这是不必要重建的头号原因。
2. Outputs路径中的易变（volatile）属性——如果输出路径包含每次构建都变化的内容（时间戳、构建号、随机 GUID），MSBuild 永远找不到上一次的输出，于是永远重建。
3. 写入位置超出了被跟踪的Outputs——目标写了文件但没写进它的Outputs，MSBuild 对这些文件一无所知：目标可能因为"声明的输出已最新"而被跳过，但下游目标仍可能被触发。
4. 缺少FileWrites注册——构建期间创建但未注册到FileWrites项组的文件，dotnet clean不会清理。久而久之陈旧文件堆积，反而干扰增量检查。
5. Glob 变化——增删源文件会使项集（如@(Compile)）变化。由于这些项会流入Inputs，输入集合改变就会触发重建。这是预期行为，但常常令人意外。
6. 属性变化——流入Inputs或Outputs路径的属性（如$(Configuration)、$(TargetFramework)）改变会导致重建。Debug 与 Release 之间切换本来就是一次完整重建，属设计使然。
7. NuGet 包更新——改包版本会更新project.assets.json，并可能改变大量已解析的程序集路径，从而改变ResolveAssemblyReferences和CoreCompile的输入，触发重建。
8. 构建服务器 VBCSCompiler 缓存失效——Roslyn 编译器服务器（VBCSCompiler）会缓存编译状态。如果服务器被回收（超时、崩溃或手动杀掉），即使 MSBuild 的增量检查通过，下一次构建仍可能更慢，因为编译器必须重新填充内存缓存。

前 4 类属于"自定义构建逻辑写错"，是本 Skill 的主战场；后 4 类属于"输入集合本质变化"，多数是预期行为，重点是能识别出来、避免误诊。需要强调的是，这类问题与求值（evaluation）阶段性能问题有明确边界：若慢在"编译开始之前"，应转向 eval-performance Skill，其 description 中明确标注"增量构建问题请使用 incremental-build"。

诊断"为什么重编了"：binlog 三步走

不要凭感觉猜。用二进制日志（binlog）精确还原"哪些目标执行了、为什么执行"。

第一步：连续构建两次，各留一份 binlog

dotnet build /bl:first.binlog dotnet build /bl:second.binlog

第一次构建建立基线，第二次构建才是你期望"增量"的那次——分析second.binlog。关于 binlog 的生成细节（例如用{}占位符自动生成唯一文件名、PowerShell 下需转义为{{}}、以及为什么禁止裸用/bl），详见配套的 binlog-generation Skill；该 Skill 强调"每一次 MSBuild 调用都要单独传/bl:{}"，保证多个配置、多次重试的日志互不覆盖，为增量对比提供可靠素材。

第二步：首选 binlog MCP 工具

本插件随 dotnet-msbuild 一同提供binlog MCP server（Microsoft.AITools.BinlogMcp，暴露在binlogMCP 命名空间下），无需把二进制日志转成文本即可结构化查询：

1. 用 overview 工具查看整体构建状态与耗时；
2. 用 search 工具查找"执行"与"跳过"的目标——搜索"Building target completely"、"Building target incrementally"、"Skipping target"；
3. 用 search 工具查找"is newer than output"消息，定位究竟是哪个输入文件触发了重建；
4. 用 target 相关工具（target_reasons、project_targets）检查特定目标为何运行；
5. 用expensive_targets工具找出第二次构建中耗时最长的目标——它们就是你的优化对象。

该流程与 binlog-failure-analysis Skill 的约束一致：binlog 是二进制格式，绝不能cat、head、strings直接读，只能通过 MCP 工具查询。

第三步（MCP 不可用时的回退）：文本日志回放

在旧 SDK 或离线环境无法启动 MCP 服务器时，把第二个 binlog 回放为诊断文本日志：

dotnet msbuild second.binlog -noconlog -fl -flp:v=diag;logfile=second-full.log;performancesummary

（PowerShell 下需将分号参数整体加引号：-flp:"v=diag;logfile=second-full.log;performancesummary"。）

然后搜索实际执行过的目标：

grep 'Building target\|Target.*was not skipped' second-full.log

在理想的增量构建中，绝大多数目标应当被跳过。再检查未跳过的目标对应的执行消息，并重点查看三类关键消息：

• "Building target 'X' completely"—— MSBuild 没找到任何输出或输出全部缺失，属于完整执行；
• "Building target 'X' incrementally"—— 部分输出已过期；
• "Skipping target 'X' because all output files are up-to-date"—— 目标被正确跳过。

最后，用下面这条命令找出具体是哪个输入文件过期：

grep "is newer than output" second-full.log

它会精确暴露是哪个输入文件的时间戳导致 MSBuild 判定目标过期。

其他辅助诊断手段

• 把first.binlog与second.binlog在 MSBuild Structured Log Viewer 中并排对比，观察两次构建的差异；
• 用grep 'Target Performance Summary' -A 30 second-full.log查看第二次构建中耗时最长的目标，这些就是优化对象；
• 留意"零耗时但仍然执行"的目标——它们可能带着不必要的依赖链，导致整条链被连带执行。

FileWrites 与 Clean：让生成文件"被看见、被清理"

FileWrites项组是 MSBuild 跟踪构建期生成文件的机制，它支撑dotnet clean，也帮助维持正确的增量行为。

• FileWrites项：自定义目标创建的每个文件都应注册，dotnet clean才知道要删除它。不注册的话，生成文件会跨构建累积，并可能干扰增量检查；
• FileWritesShareable项：用于跨多个项目共享的文件（如共享生成代码）。这些文件会被跟踪，但如果其他项目仍引用它们，则不会删除；
• 不注册的后果：文件堆积在输出目录与中间目录，dotnet clean不会移除它们，可能造成陈旧数据或混淆 up-to-date 检查。

注册生成文件的推荐模式是"在创建它的目标内部就地添加"：

<Target Name="MyGenerator" Inputs="..." Outputs="$(IntermediateOutputPath)generated.cs"> <!-- Generate the file --> <WriteLinesToFile File="$(IntermediateOutputPath)generated.cs" Lines="@(GeneratedLines)" /> <!-- Register for clean --> <ItemGroup> <FileWrites Include="$(IntermediateOutputPath)generated.cs" /> </ItemGroup> </Target>

配套的 including-generated-files Skill 进一步解释了深层原因：文件在构建执行阶段才生成，而 glob 在求值阶段就已展开，所以执行期创建的文件天然"不可见"，必须手动加入Compile/FileWrites，并在正确的BeforeTargets时机（生成源码用CoreCompile;BeforeCompile，非代码文件用BeforeBuild，兜底用AssignTargetPaths）注入。该 Skill 还给出了 glob 行为对照表：目标外部的 glob 只能捕获求值期可见的文件，目标内部的 glob 才能捕获执行期已生成的文件——这正是把<ItemGroup>放进<Target>的原因。同时它强调始终使用$(IntermediateOutputPath)而不是硬编码obj\$(Configuration)\$(TargetFramework)\，因为中间输出路径可能被重定向（共享输出目录、CI 环境）。

区分 VS 的 Fast Up-to-Date Check（FUTDC）

Visual Studio 有一套独立于 MSBuildInputs/Outputs机制的自身 up-to-date 检查（Fast Up-to-Date Check，FUTDC）。不理解两者的区别，就无法诊断"VS 里重编、命令行却不重编"这类诡异问题。

• FUTDC 更快：它进程内运行，不调用 MSBuild，只把一组已知项类型（Compile、Content、EmbeddedResource等）的时间戳与项目主输出比较；
• 它可能判错：如果项目使用自定义构建操作、生成文件的自定义目标、或 FUTDC 不认识的非标准项类型，检查结果就会失真；
• 关闭 FUTDC，强制 VS 走 MSBuild 的完整增量检查：

<PropertyGroup> <DisableFastUpToDateCheck>true</DisableFastUpToDateCheck> </PropertyGroup>

• 诊断 FUTDC 的决策：在 VS 中打开工具 → 选项 → 项目和解决方案 → SDK 风格项目，把Up-to-date 检查的日志级别设为Verbose或更高。FUTDC 会逐条记录它认为"过期"的具体文件；
• VS FUTDC 常见问题：
  • 自定义构建操作未注册到 FUTDC 系统；
  • 比上次构建更新的CopyToOutputDirectory项；
  • 由目标动态添加、FUTDC 未求值的项；
  • 带CopyToOutputDirectory="PreserveNewest"且被修改过的Content或None项。

编写真正增量的自定义 Target：完整示例与常见错误

下面是一个结构良好的增量自定义目标完整示例：

<Target Name="GenerateConfig" Inputs="$(MSBuildProjectFile);@(ConfigInput)" Outputs="$(IntermediateOutputPath)config.generated.cs" BeforeTargets="CoreCompile"> <!-- Generate file only if inputs changed --> <WriteLinesToFile File="$(IntermediateOutputPath)config.generated.cs" Lines="..." /> <ItemGroup> <FileWrites Include="$(IntermediateOutputPath)config.generated.cs" /> <Compile Include="$(IntermediateOutputPath)config.generated.cs" /> </ItemGroup> </Target>

各关键点的设计意图：

• Inputs包含$(MSBuildProjectFile)：保证项目文件本身变化（例如影响了生成的属性被修改）时目标会重跑；
• Inputs包含@(ConfigInput)：真正的生成驱动源文件；
• Outputs使用$(IntermediateOutputPath)：生成文件放进obj/，由 MSBuild 管理并自动清理；
• BeforeTargets="CoreCompile"：保证编译前生成文件已就绪；
• FileWrites注册：保证dotnet clean能删除生成文件；
• Compile加入：把生成文件纳入编译，且不要求在求值期文件已存在。

这与 target-authoring Skill 的规范完全同源：它给出了 Build→CoreBuild 三级目标链、$(XxxDependsOn)链式追加（追加而非覆盖，覆盖会悄悄丢掉 SDK 目标）、以及DependsOnTargets/BeforeTargets/AfterTargets的选择表——当你"不拥有"某条流水线时，用BeforeTargets/AfterTargets注入；BeforeTargets="CoreCompile"优先于改$(CompileDependsOn)。此外该 Skill 还明确了目标命名约定（_Xxx内部目标、CoreXxx实现、BeforeXxx/AfterXxx空扩展钩子、GetXxx轻量查询），并警示"在.props中定义目标会导致BeforeTargets无从挂钩，目标应放进.targets"。

常见错误对照

<!-- BAD: 没有 Inputs/Outputs —— 每次构建都运行 --> <Target Name="BadTarget" BeforeTargets="CoreCompile"> <Exec Command="generate-code.exe" /> </Target> <!-- BAD: 易变输出路径 —— 永远找不到上一次的输出 --> <Target Name="BadTarget2" Inputs="@(Compile)" Outputs="$(OutputPath)gen_$([System.DateTime]::Now.Ticks).cs"> <Exec Command="generate-code.exe" /> </Target> <!-- GOOD: 稳定路径、注册输出 --> <Target Name="GoodTarget" Inputs="@(Compile)" Outputs="$(IntermediateOutputPath)generated.cs" BeforeTargets="CoreCompile"> <Exec Command="generate-code.exe -o $(IntermediateOutputPath)generated.cs" /> <ItemGroup> <FileWrites Include="$(IntermediateOutputPath)generated.cs" /> <Compile Include="$(IntermediateOutputPath)generated.cs" /> </ItemGroup> </Target>

BadTarget2中的$([System.DateTime]::Now.Ticks)是典型反例：输出文件名每次构建都不同，增量检查永远找不到"上一次的输出"，于是退化为全量执行。这也呼应了"避免在构建中嵌入易变数据"的总原则。

PerformanceSummary 与 Preprocess：两条内置透视工具

MSBuild 自带两个低成本工具，帮助你快速理解"什么在跑、为什么跑"：

• /clp:PerformanceSummary—— 在构建结束时追加摘要，展示每个目标和任务花费的时间。快速定位最昂贵的操作：

dotnet build /clp:PerformanceSummary

它会输出一张按累计耗时排序的目标表，方便你一眼找出"增量构建里根本不该运行"的目标。该开关同样适用于回放场景（前述performancesummary参数即其日志版）。

• /pp:preprocess.xml—— 生成一个内联了全部导入的单一 XML，即"完全求值后的项目"。对理解哪些目标、属性、项被定义以及来自哪里价值极大：

dotnet msbuild /pp:preprocess.xml

在预处理输出中搜索任意目标的Inputs/Outputs定义，或理清整条导入链。该工具与 eval-performance Skill 的用法一致：预处理输出超过约 1 万行通常意味着求值负担偏重，可配合其"求值五阶段"模型进一步定位。

两者结合使用：用PerformanceSummary看"什么在跑"，用/pp看"什么被导入"，再与 binlog 分析交叉印证，即可拼出完整图景。

常见修复清单

• 永远给自定义 Target 添加Inputs和Outputs——这是对增量构建性能影响最大的一步。缺任何一个属性，目标都会每次执行；
• 生成文件使用$(IntermediateOutputPath)——obj/下的文件由 MSBuild 的清理基础设施跟踪，不会跨配置泄漏；
• 在FileWrites中注册生成文件——保证dotnet clean删除它们，防止陈旧文件堆积；
• 避免构建中的易变数据——不要把时间戳、随机值、构建计数器嵌进文件路径或生成内容，除非你有刻意设计的过期管理策略。确需使用易变数据时，把它隔离到单一文件，最小化下游影响；
• 需要传递项但不想建立增量依赖时，用Returns而非Outputs——Outputs身兼两职：既定义增量检查，又作为目标返回的项。如果只是想给调用方传项而不影响增量性，用Returns：

<!-- Outputs: 既影响增量检查，也影响返回值 --> <Target Name="GetFiles" Outputs="@(DiscoveredFiles)">...</Target> <!-- Returns: 只影响返回值，不参与增量检查 --> <Target Name="GetFiles" Returns="@(DiscoveredFiles)">...</Target>

这一点在 target-authoring Skill 中被进一步强调：在查询目标（GetTargetPath、GetTargetFrameworks）上误用Outputs，会导致目标"看似最新"而被跳过、返回陈旧数据；查询目标应始终使用Returns。

收尾：用两次构建验证修复效果

修复完成后，回到诊断的第一步做闭环验证：再次连续执行两次构建并各留一份 binlog，在第二次构建的日志（或 MCP 查询结果）中确认自定义目标出现了Skipping target ... because all output files are up-to-date，且grep "is newer than output"不再命中预期外的输入文件。这正是 incremental-build 评估用例 的最终 rubric——"构建两次验证增量性（第二次应跳过该目标）"——也是本 Skill 期望 Agent 交付的落地标准。当"第二次构建仍然全量重编"时，按 8 大根因逐一对照排查，配合 binlog-failure-analysis 与 target-authoring 等姊妹 Skill 协同分析，绝大多数增量失效问题都能在几分钟内定位并修复。

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills