.NET Core3.1项目Azure DevOps CI构建后appsettings文件未合并问题

核心逻辑说明 #

.NET Core 3.1 框架默认不会在构建/发布阶段自动合并不同环境的appsettings文件，两个文件同时出现在输出目录是框架默认行为，不属于CI管道错误。
这类问题90%的诱因是混淆了两个完全独立的概念：

• -c Release指定的是MSBuild构建配置，只控制编译优化、调试符号输出这类编译期行为，和配置文件加载逻辑没有任何绑定关系
• 运行时加载哪个环境的配置文件，完全由ASPNETCORE_ENVIRONMENT环境变量决定，框架内置默认值是Production，不会因为你用Release配置构建就自动加载appsettings.Release.json

排查&解决步骤 #

• 先验证本地发布行为
  在项目根目录本地执行命令：

  dotnet publish -c Release -o ./test-publish
  

  如果本地test-publish目录里同样存在appsettings.json和appsettings.Release.json两个文件，说明问题和Azure DevOps管道无关，是框架默认逻辑符合预期，不需要排查CI配置。
• 检查运行时配置加载逻辑
  如果你遇到的是「Release环境的配置值不生效」，而不是非要合并成单个文件：
  1. 确认部署目标环境（比如Azure App Service、虚拟机）的环境变量里，ASPNETCORE_ENVIRONMENT的值被显式设置为Release，否则框架只会默认找appsettings.Production.json，你写的Release配置文件就算存在于目录中也不会被加载
  2. launchSettings.json里的环境变量配置只对本地调试生效，CI构建、生产部署阶段完全不会读取这个文件的内容，不要靠这个文件配置部署环境的标识
• 检查.csproj文件的配置项
  打开项目的.csproj文件，确认appsettings相关的配置没有被错误修改，默认正确的配置如下：

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    </None>
    <None Update="appsettings.Release.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  

  不要随意给配置文件加<CopyToPublishDirectory>Never</CopyToPublishDirectory>配置，否则会导致对应环境配置文件不会被输出到发布目录。
• 如果确实需要构建后只输出单个合并后的appsettings.json
  框架原生不提供这个能力，你需要自行添加构建步骤实现：
  1. 可以在.csproj里加一个发布后执行的Target，在Release构建完成后，将appsettings.Release.json的配置项覆盖合并到输出目录的appsettings.json中，再删除多余的appsettings.Release.json文件
  2. 也可以在Azure DevOps CI管道里，在dotnet publish步骤之后加一个JSON转换任务，完成配置合并和冗余文件删除操作，不需要修改项目代码。

补充说明：除非你有明确的单配置文件合规要求，否则不建议做构建阶段合并。框架原生的多文件按需加载逻辑是官方推荐的最佳实践，只需要正确配置部署环境的ASPNETCORE_ENVIRONMENT变量即可正常工作，不需要额外做合并操作。

内容的提问来源于stack exchange，提问作者Surya