使用Azure Bicep部署私有Docker镜像Web App报错：LinuxFxVersion值无效

问题原因 #

The parameter LinuxFxVersion has an invalid value 错误的核心原因是私有镜像的格式不符合Azure要求，同时存在App Service Plan配置缺失的问题。

解决方案 #

1. 修正linuxFxVersion格式 #

私有Docker镜像的linuxFxVersion必须包含完整的无协议镜像路径和标签，格式为：

DOCKER|<registry-domain>/<image-name>:<tag>

示例：

• Azure容器注册表：DOCKER|myacr.azurecr.io/my-app-image:v1
• Docker Hub私有镜像：DOCKER|docker.io/myusername/my-app-image:v1

注意：

• 必须明确指定镜像标签（不能省略，确保镜像在注册表中存在）
• 路径不能包含http://或https://前缀

2. 完整修正后的Bicep配置 #

需要给App Service Plan添加kind: 'linux'属性（否则无法支持Linux容器），同时调整linuxFxVersion的格式：

// 修正App Service Plan，添加Linux类型声明
resource appServicePlan 'Microsoft.Web/serverfarms@2020-12-01' = {
  dependsOn: [
    appConfiguration
  ]
  name: 'ASP-ap-${environment}-01'
  location: location
  kind: 'linux' // 必须指定为Linux计划
  sku: {
    name: 'F1'
    capacity: 1
  }
}

resource webApplication 'Microsoft.Web/sites@2022-09-01' = {
  name: 'wa-service-${environment}'
  location: location
  tags: commonTags
  kind: 'app,linux,container'
  properties: {
    serverFarmId: appServicePlan.id
    siteConfig: {
      appSettings: [
        {
          name: 'DOCKER_REGISTRY_SERVER_URL'
          value: dockerRegistryUrl // 这里需要带协议，比如https://myacr.azurecr.io
        }
        {
          name: 'DOCKER_REGISTRY_SERVER_USERNAME'
          value: dockerRegistryUsername
        }
        {
          name: 'DOCKER_REGISTRY_SERVER_PASSWORD'
          value: dockerRegistryPassword
        }
      ]
      // 处理registry URL，移除协议前缀后拼接镜像信息
      linuxFxVersion: 'DOCKER|${replace(dockerRegistryUrl, 'https://', '')}/${imageName}:${imageTag}'
    }
  }
}

3. 优化部署命令 #

建议使用Incremental部署模式（Complete模式会删除资源组内未在模板中定义的资源，风险较高）：

az deployment group create --resource-group rg-test --template-file .\test.bicep --mode Incremental

4. 验证步骤 #

部署完成后，可通过CLI确认配置是否生效：

az webapp config show --resource-group rg-test --name wa-service-${environment} --query 'linuxFxVersion'

或在Azure门户的Web App「容器设置」中查看镜像配置是否正确。

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