.NET 6中如何基于生成配置动态切换appsettings.json

核心思路：利用.NET原生环境配置机制+CI/CD环境变量传递 #

.NET 6本身提供了基于环境的配置加载逻辑，无需手动修改appsettings.json，只需通过环境变量指定当前运行环境，应用会自动加载对应的appsettings.{Environment}.json配置，同时覆盖基础appsettings.json中的同名项。结合Gitlab CI/CD的环境变量设置，就能实现完全自动化的配置切换。

1. 确保配置文件正确纳入项目 #

确保所有环境配置文件（appsettings.Development.json、appsettings.Staging.json、appsettings.Production.json）都被包含在项目中，无需在.csproj中写复杂的复制规则。只需在.csproj里确认以下配置（默认已包含，若缺失可添加）：

<ItemGroup>
  <Content Include="appsettings.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
  <Content Include="appsettings.*.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <DependentUpon>appsettings.json</DependentUpon>
  </Content>
</ItemGroup>

这样所有环境配置文件都会被复制到输出目录，供应用启动时加载。

2. 配置Program.cs自动加载环境配置 #

.NET 6的默认模板已经包含了环境配置加载逻辑，确认你的Program.cs中有以下代码（顶级语句模式）：

var builder = WebApplication.CreateBuilder(args);

// 自动加载对应环境的配置文件：appsettings.{Environment}.json
// 优先级：环境变量 > 环境配置文件 > 基础appsettings.json
builder.Configuration
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true, reloadOnChange: true)
    .AddEnvironmentVariables();

这段代码会根据ASPNETCORE_ENVIRONMENT环境变量的值，自动加载对应的配置文件，并且环境变量的优先级最高（如果需要临时覆盖也可以用，但你倾向项目内配置，所以主要靠环境配置文件）。

3. Gitlab CI/CD配置：传递环境变量+强制干净构建 #

在Gitlab CI/CD的.gitlab-ci.yml中，为不同环境的部署阶段设置对应的ASPNETCORE_ENVIRONMENT变量，并确保每次构建都是干净的，避免旧配置残留：

示例CI配置：

stages:
  - build
  - deploy-dev
  - deploy-staging
  - deploy-prod

# 通用构建模板
.build_template:
  stage: build
  script:
    # 强制清理旧构建产物，避免增量构建导致的配置不一致
    - dotnet clean
    # 构建时指定环境（可选，若需要在构建阶段生成特定环境的配置，可加/p:EnvironmentName=$ENV_NAME）
    - dotnet build --configuration Release --no-incremental
    - dotnet publish --configuration Release --output ./publish
  artifacts:
    paths:
      - ./publish

# 开发环境部署
deploy-dev:
  extends: .build_template
  variables:
    ENV_NAME: Development
    ASPNETCORE_ENVIRONMENT: Development
  only:
    - dev

# 预发布环境部署
deploy-staging:
  extends: .build_template
  variables:
    ENV_NAME: Staging
    ASPNETCORE_ENVIRONMENT: Staging
  only:
    - staging

# 生产环境部署
deploy-prod:
  extends: .build_template
  variables:
    ENV_NAME: Production
    ASPNETCORE_ENVIRONMENT: Production
  only:
    - main
  when: manual # 生产环境建议手动触发

• dotnet clean + --no-incremental：确保每次构建都是全新的，彻底解决非完全重建导致的配置残留问题。
• ASPNETCORE_ENVIRONMENT变量：传递给应用，启动时自动加载对应环境的配置文件。

4. 验证配置正确性 #

为了避免配置加载错误，可在应用启动时添加日志输出当前环境和关键配置（注意不要输出敏感信息，比如完整连接字符串）：

var app = builder.Build();

// 输出当前环境名称
app.Logger.LogInformation("当前运行环境: {EnvironmentName}", app.Environment.EnvironmentName);
// 输出连接字符串的部分信息（比如数据库名称）验证是否正确
var connString = builder.Configuration.GetConnectionString("DefaultConnection");
if (!string.IsNullOrEmpty(connString))
{
    // 提取数据库名称示例（根据连接字符串格式调整）
    var dbName = connString.Split(';').FirstOrDefault(s => s.StartsWith("Database="))?.Split('=')[1];
    app.Logger.LogInformation("当前数据库: {DbName}", dbName);
}

这样在CI/CD部署后，通过日志就能快速确认配置是否正确加载。

5. 替代方案：构建时替换配置（可选） #

如果需要在构建阶段就将对应环境的配置合并到appsettings.json中（比如某些场景下要求输出目录只有一个配置文件），可以用MSBuild的TransformXml任务实现配置转换：

1. 在.csproj中添加TransformXml任务引用：

<UsingTask TaskName="TransformXml" AssemblyFile="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Web\Microsoft.Web.Publishing.Tasks.dll" />

2. 添加构建时的转换目标：

<Target Name="TransformAppSettings" AfterTargets="Build">
  <TransformXml Source="appsettings.json" Transform="appsettings.$(EnvironmentName).json" Destination="$(OutputPath)\appsettings.json" />
</Target>

然后在CI构建时通过dotnet build /p:EnvironmentName=Production指定环境，就能自动将生产配置合并到输出的appsettings.json中。不过这种方式不如原生环境加载灵活，建议优先使用前面的方案。

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