ASP.NET Core 配置系统优先级

在 ASP.NET Core 中配置系统的核心设计原则是**“后添加的源覆盖先添加的源”**。这意味着在构建IConfiguration时越晚被添加到 ConfigurationBuilder 中的配置源其优先级越高。以下是默认主机生成器WebApplication.CreateBuilder/Host.CreateDefaultBuilder下配置源从低到高的标准优先级顺序 标准配置优先级由低到高ChainedConfigurationSource框架内部默认值appsettings.json— 基础配置文件appsettings.{Environment}.json— 环境特定配置如appsettings.Production.json覆盖appsettings.json中的同名键User Secrets仅 Development 环境生效环境变量Environment Variables命令行参数Command-line Arguments—最高优先级⚠️核心记忆口诀文件 用户密钥 环境变量 命令行同一层级内环境特定文件 通用文件。 关键细节与注意事项1. 同 Key 覆盖机制配置系统使用扁平化的键如ConnectionStrings:Default。当多个源提供同一个键时高优先级源的值完全替换低优先级源的值不是合并。// appsettings.json: Logging:LogLevel:Default Information// 环境变量: Logging__LogLevel__Default Warning// ✅ 最终结果: Warning环境变量覆盖了JSON文件2. 自定义配置源的插入位置决定优先级当你手动添加配置源时代码中的调用顺序直接决定了优先级builder.Configuration.AddJsonFile(custom-low.json)// 优先级较低.AddJsonFile(custom-high.json);// 优先级较高覆盖上面的同名键如果需要在所有默认源之后追加一个最高优先级的源直接在CreateBuilder之后调用即可如果想让它优先级低于环境变量则需要操作ConfigurationManager.Sources集合手动调整顺序。3. User Secrets 的安全边界仅在Development环境自动加载Production/Staging 环境中即使存在 secrets 文件也不会被读取生产环境的敏感信息应通过环境变量或Azure Key Vault / AWS Secrets Manager等外部配置提供程序注入4. 环境变量命名约定由于环境变量不支持:分隔符部分平台限制ASP.NET Core 支持双下划线__作为替代JSON 键环境变量名ConnectionStrings:DefaultConnectionStrings__DefaultLogging:LogLevel:DefaultLogging__LogLevel__Default 调试技巧查看实际生效的配置顺序在开发阶段可以通过以下代码确认当前所有配置源及其顺序foreach(varproviderinbuilder.Configuration.Providers){Console.WriteLine(provider.GetType().Name);}输出顺序即为从低到高的优先级顺序最后输出的 Provider 拥有最高话语权。