Azure App Service无法覆盖appsettings.json连接字符串问题排查

核心问题拆解 #

你遇到的是Azure App Service配置的连接字符串未被程序正确读取，导致抛出The ConnectionString property has not been initialized.错误。结合你试过的操作（移除环境变量加载、设置appsettings初始值无效），重点从配置优先级、Azure配置格式、代码读取逻辑这几个方向排查。

1. 核对Azure端连接字符串的配置细节 #

• 连接字符串的名称必须和代码里的ConnStr完全匹配，大小写敏感（Linux部署环境下尤其要注意）。
• 连接字符串的类型选择要正确：SQL Server数据库选「SQL Server」，自定义连接字符串选「Custom」——类型错误会导致Azure不将其注入环境变量，程序自然读不到。

2. 确认配置加载的优先级顺序 #

ASP.NET Core中环境变量的优先级高于本地appsettings配置，所以AddEnvironmentVariables()必须放在配置加载链的最后，确保Azure的环境变量能覆盖本地配置。示例代码：

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")}.json", optional: true)
    .AddEnvironmentVariables() // 放在最后，保证Azure配置覆盖本地
    .Build();

如果你之前移除过这个方法后又重新添加，务必检查位置是否正确。

3. 检查代码读取连接字符串的方式 #

推荐用框架提供的Configuration.GetConnectionString("ConnStr")方法读取，而非直接通过索引器Configuration["ConnectionStrings:ConnStr"]（虽然后者也能工作，但前者专门处理连接字符串的解析逻辑，更可靠）。

比如在DbContext配置中：

optionsBuilder.UseSqlServer(Configuration.GetConnectionString("ConnStr"));

如果用索引器，要确认层级路径是否正确，用冒号分隔层级。

4. 验证Azure配置是否真正生效 #

• 修改配置后必须重启App Service，部分场景下配置不会自动热加载。
• 通过Kudu工具验证环境变量：进入App Service的「高级工具」→「Kudu」→「环境变量」，搜索ConnectionStrings__ConnStr（Azure会将连接字符串转换为双下划线分隔的环境变量格式），如果找不到这个变量，说明Azure的配置未正确保存，需要重新提交配置。

5. 本地模拟Azure环境测试 #

本地测试时，设置系统环境变量ConnectionStrings__ConnStr（注意双下划线），然后启动程序，看是否能正常读取。如果本地能读到，说明代码逻辑没问题，问题出在Azure的配置或部署环节。

6. 检查appsettings.json结构正确性 #

确保appsettings.json的ConnectionStrings结构无误：

{
  "ConnectionStrings": {
    "ConnStr": ""
  }
}

结构错误会导致本地配置加载失败，即使Azure有值也无法完成覆盖。

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