必须通过 IConfiguration 加载 appsettings.json，而非 File.ReadAllText 或 JsonSerializer.Deserialize，否则无法支持环境区分、层级映射、类型转换、热重载及多源合并；正确方式是用 ConfigurationBuilder.AddJsonFile 并配合 IOptionsMonitor 实现配置热更新。
直接读取 appsettings.json 不能靠 File.ReadAllText 硬解析——它需要被 IConfiguration 实例加载并绑定，否则你拿不到环境区分、层级展开、类型转换和重载刷新能力。
为什么 ConfigurationBuilder 必须调用 AddJsonFile 而不是手动反序列化？
手动用 JsonSerializer.Deserialize 读取 appsettings.json 只能得到原始 JSON 对象，无法支持：
-
appsettings.Development.json的自动覆盖逻辑 -
Logging:LogLevel:Default这种冒号分隔的层级键自动映射到 C# 层级对象 -
IOptionsMonitor<t></t>的热重载（修改文件后自动更新） - 环境变量、命令行参数等其他源的合并优先级控制
正确做法是让 ConfigurationBuilder 统一接管：
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json",
optional: true, reloadOnChange: true)
.Build();
IConfiguration 和 IOptions<t></t> 该选哪个？
直接用 IConfiguration 适合简单场景（如读一个连接字符串），但容易出错；IOptions<t></t> 更安全、可测试、支持验证。区别如下：
-
IConfiguration["ConnectionStrings:Default"]→ 返回string，拼错键名或类型不匹配时运行时报错 -
IOptions<appsettings>.Value.DatabaseTimeout</appsettings>→ 编译期检查字段存在性，启动时校验类型和必需项 - 若需响应配置变更，必须用
IOptionsMonitor<t></t>，IOptionsSnapshot<t></t>只在作用域内快照一次
注册示例（.NET 6+ Program.cs）：
builder.Services.Configure<AppSettings>(builder.Configuration.GetSection("AppSettings"));
// 或启用热重载
builder.Services.ConfigureMonitor<AppSettings>(builder.Configuration.GetSection("AppSettings"));
读取嵌套对象或数组时常见的 key 写法错误
JSON 中的数组和对象在 IConfiguration 里统一转为扁平 key，冒号是层级分隔符，索引用方括号——但不能写成 MyList[0].Name，而要写成 MyList:0:Name：
{
"Features": {
"Enabled": true,
"Modules": [ { "Name": "Auth", "Version": "2.1" } ]
}
}
对应读取方式：
-
config.GetValue<bool>("Features:Enabled")</bool>✅ -
config.GetSection("Features:Modules:0").GetValue<string>("Name")</string>✅（注意是:0，不是[0]） -
config.GetSection("Features:Modules").Get<list>>()</list>✅（需类定义 +Get<t></t>） -
config["Features:Modules[0]:Name"]❌ 不识别方括号语法
部署时 appsettings.json 文件找不到或没生效？检查这三点
常见原因不是代码问题，而是发布/部署细节遗漏：
- 确保
.csproj中包含：<content include="appsettings*.json" copytooutputdirectory="PreserveNewest"></content> - Linux 容器中路径大小写敏感：
AppSettings.json≠appsettings.json，文件名必须全小写 -
reloadOnChange: true在 IIS 或某些托管服务中无效（文件系统通知被禁用），此时修改配置需重启应用
最稳妥的调试方式：启动后立刻打印 config.AsEnumerable() 查看实际加载了哪些键值对，比猜路径更直接。
