C# .NET项目中 appsettings.json 与 appsettings.Development.json 的区别与使用

在Visual Studio中新增一个Web API项目后，会出现两个配置文件，对于初学者可能会有点疑惑，我的配置信息要写在哪个里面？

 一、核心区别

特性	appsettings.json	appsettings.Development.json
核心定位	全局基础配置文件，所有环境的配置基底	开发环境专属配置文件，仅开发环境生效
加载规则	项目启动时始终优先加载，必选	仅当ASPNETCORE_ENVIRONMENT环境变量值为Development时才会加载，可选
优先级	最低，同 Key 配置会被环境专属文件覆盖	高于基础 appsettings.json，同 Key 配置会直接覆盖前者
适用场景	存放所有环境通用的配置（如全局日志规则、应用名称、通用业务规则、固定配置结构）	存放开发环境差异化配置（如本地数据库连接、测试密钥、调试级别的日志、本地第三方服务地址）

二、底层加载机制

ASP.NET Core 的WebApplication.CreateBuilder(args)会按固定顺序加载配置，后加载的配置会覆盖先加载的同 Key 配置，默认顺序为：

1. appsettings.json
2. appsettings.{环境名称}.json（如Development/Production）
3. 系统环境变量
4. 命令行参数

也就是说，开发环境下，两个文件都会加载，最终生效的是合并后的配置，重复的 Key 以appsettings.Development.json为准。

三、正确使用方法

1. 配置运行环境
   配置文件的加载完全由ASPNETCORE_ENVIRONMENT环境变量控制：
   开发阶段：默认在Properties/launchSettings.json中已经配置好环境变量，默认值就是Development，调试时自动生效，无需额外修改。
   

   

    部署阶段：通过操作系统环境变量、Docker 的 ENV 指令、IIS 的 web.config、K8S 配置等设置环境变量，生产环境一般设置为Production，此时只会加载appsettings.json和appsettings.Production.json，不会加载开发环境的配置。

2. 配置文件的编写规范
   核心原则：通用配置放基础文件，环境差异化配置放对应环境文件，举最常用的示例：
   ① appsettings.json（通用基底）
   存放所有环境都通用的配置，固定的配置结构，避免环境相关的敏感信息：
   

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     // 预留配置结构，具体值由环境文件填充
     "ConnectionStrings": {
       "Default": ""
     },
     "Jwt": {
       "Issuer": "Dormitory.AuthService",
       "Audience": "Dormitory.Client"
     }
   }

   ② appsettings.Development.json（开发环境覆盖）

   {
     "Logging": {
       "LogLevel": {
         "Default": "Debug", // 开发环境开Debug级日志，覆盖基础的Information
         "Microsoft.AspNetCore": "Debug"
       }
     },
     // 开发环境本地数据库连接
     "ConnectionStrings": {
       "Default": "Server=localhost;Database=DormitoryAuth_Dev;Uid=root;Pwd=123456;"
     },
     // 开发环境测试用JWT密钥
     "Jwt": {
       "SecretKey": "开发环境专用的测试密钥，无需严格加密"
     }
   }

代码中读取配置
.NET 的配置系统会自动合并所有配置文件，你无需关心配置来自哪个文件，统一通过IConfiguration读取即可，用法完全一致：
示例 1：Program.cs 中读取

var builder = WebApplication.CreateBuilder(args); // 读取数据库连接字符串 var connStr = builder.Configuration.GetConnectionString("Default"); // 读取JWT配置 var jwtSecret = builder.Configuration["Jwt:SecretKey"]; var jwtIssuer = builder.Configuration["Jwt:Issuer"];

示例 2：Controller 中注入读取

[ApiController] [Route("api/[controller]")] public class AuthController : ControllerBase { private readonly IConfiguration _configuration; // 构造函数注入IConfiguration public AuthController(IConfiguration configuration) { _configuration = configuration; } [HttpGet] public IActionResult GetConfig() { var secretKey = _configuration["Jwt:SecretKey"]; return Ok(secretKey); } }

四、最佳实践与避坑指南

1. 不要重复配置
   通用配置只在appsettings.json里写一次，环境文件只写需要覆盖的差异化配置，减少冗余。
2. 确保文件正确发布
   右键配置文件 → 属性 → 复制到输出目录，必须设置为如果较新则复制，否则发布后文件不会被打包到程序目录，导致配置加载失败（VS 创建项目时默认已正确设置）。
   

   

3. 扩展其他环境
   该机制支持自定义环境，比如测试环境可以新增appsettings.Staging.json，预发布环境新增appsettings.PreRelease.json，只需对应设置环境变量即可自动加载。
4. 环境与编译模式无关
   不是只有 Debug 模式才会加载 Development.json，只要环境变量设为Development，哪怕是 Release 发布的程序，也会加载该文件，生产环境务必不要设置该环境变量。