如何在Azure Functions中使用环境/配置专属local.settings.json

问题根源分析 #

你遇到的重复键异常，是因为 Azure Functions 运行时会自动读取 LOCAL_SETTINGS_FILE 环境变量指定的配置文件，而你手动调用 AddJsonFile 又加载了一次同名/同键的配置，导致重复加载同一配置项引发冲突。

正确实现步骤 #

1. 配置多环境配置文件 #

创建对应环境的配置文件，仅保留当前环境需要覆盖的配置项（通用配置放在基础文件中）：

• 基础配置文件 local.settings.json：

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "ApplicationSettings:AzureTableSettings:ConnectionString": "dev-connection-string"
  }
}

• Staging 环境配置文件 local.settings.Staging.json：

{
  "IsEncrypted": false,
  "Values": {
    "ApplicationSettings:AzureTableSettings:ConnectionString": "staging-connection-string"
  }
}

2. 调整 launchSettings.json #

为每个环境配置独立的启动 profile，指定对应的环境变量：

{
    "profiles": {
        "Development": {
            "commandName": "Project",
            "environmentVariables": {
                "AZURE_FUNCTIONS_ENVIRONMENT": "Development",
                "LOCAL_SETTINGS_FILE": "local.settings.json"
            }
        },
        "Staging": {
            "commandName": "Project",
            "environmentVariables": {
                "AZURE_FUNCTIONS_ENVIRONMENT": "Staging",
                "LOCAL_SETTINGS_FILE": "local.settings.Staging.json"
            }
        }
    }
}

3. 无需手动修改配置加载逻辑（默认方案） #

Azure Functions 运行时会自动根据 LOCAL_SETTINGS_FILE 加载对应配置文件，不需要在 ConfigureAppConfiguration 中手动添加 AddJsonFile，直接使用默认配置即可：

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .Build();

host.Run();

4. 自定义配置合并（可选） #

如果需要手动合并基础配置与环境配置（比如保留基础配置，用环境配置覆盖），需先移除运行时默认加载的配置源，避免重复：

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureAppConfiguration((context, config) =>
    {
        // 移除运行时默认加载的 local.settings.json 配置源
        var defaultJsonSource = config.Sources.FirstOrDefault(s => 
            s is JsonConfigurationSource json && json.Path.Contains("local.settings.json"));
        if (defaultJsonSource != null)
        {
            config.Sources.Remove(defaultJsonSource);
        }

        // 加载基础配置
        config.AddJsonFile("local.settings.json", optional: false, reloadOnChange: true);
        // 加载环境专属配置（覆盖基础配置）
        var envName = context.HostingEnvironment.EnvironmentName;
        config.AddJsonFile($"local.settings.{envName}.json", optional: true, reloadOnChange: true);
        // 加载系统环境变量（优先级最高）
        config.AddEnvironmentVariables();
    })
    .Build();

host.Run();

关键注意事项 #

• 配置优先级：系统环境变量 > 环境专属配置文件 > 基础配置文件
• AZURE_FUNCTIONS_ENVIRONMENT 是 Azure Functions 官方识别的环境变量，不要混用 NETCORE_ENVIRONMENT
• 避免手动重复加载配置文件，否则会触发重复键异常

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