Bicep 中的变量

2025-06-05

本文介绍如何在 Bicep 文件中定义和使用变量。变量用于简化 Bicep 文件开发。请定义包含复杂表达式的变量，而不必在整个 Bicep 文件中重复使用复杂的表达式。然后，在整个 Bicep 文件中根据需要使用该变量。

资源管理器会在启动部署操作之前解析变量。在 Bicep 文件中所有使用该变量的位置，资源管理器都会将其替换为解析的值。一个 Bicep 文件中最多可以包含 512 个变量。有关详细信息，请参阅模板限制。

定义变量

变量不能与参数、模块或资源同名。可以为每个变量添加一个或多个修饰器。有关详细信息，请参阅使用修饰器。

非类型化变量

在未指定数据类型的情况下定义变量时，将从值推断该类型。定义非类型化变量的语法为：

@<decorator>(<argument>)
var <variable-name> = <variable-value>

以下示例将一个变量设置为字符串。

var stringVar = 'preset variable'

构造变量时，你可以使用参数或其他变量中的值。

param inputValue string = 'deployment parameter'

var stringVar = 'preset variable'
var concatToVar =  '${stringVar}AddToVar'
var concatToParam = '${inputValue}AddToParam'

output addToVar string = concatToVar
output addToParam string = concatToParam

上述示例的输出返回：

{
  "addToParam": {
    "type": "String",
    "value": "deployment parameterAddToParam"
  },
  "addToVar": {
    "type": "String",
    "value": "preset variableAddToVar"
  }
}

可以使用 Bicep 函数来构造变量值。以下示例使用 Bicep 函数创建储帐户名称的字符串值。

param storageNamePrefix string = 'stg'
var storageName = '${toLower(storageNamePrefix)}${uniqueString(resourceGroup().id)}'

output uniqueStorageName string = storageName

前面的示例返回类似于以下输出的值：

"uniqueStorageName": {
  "type": "String",
  "value": "stghzuunrvapn6sw"
}

类型化变量

从 Bicep CLI 版本 0.36.X 开始，Bicep 支持 类型化变量，在该变量中显式声明变量的数据类型，以确保类型安全性并提高代码清晰度。类型化变量的优点：

错误检测：Bicep 编译器验证分配的值是否与声明的类型匹配，并提前捕获错误。
代码清晰：显式类型可明确变量保存的数据类型。
Intellisense 支持：Visual Studio Code 等工具为类型化变量提供更好的自动完成和验证。
重构安全性：确保对变量赋值所做的更改不会无意中中断类型预期。

若要定义类型化变量，请使用 var 关键字后跟变量名称、类型和赋值：

var <variable-name> <data-type> = <variable-value>

以下示例演示如何定义类型化变量：

var resourceName string = 'myResource'
var instanceCount int = 3
var isProduction bool = true
var tags object = { environment: 'dev' }
var subnets array = ['subnet1', 'subnet2']

对于 object 类型，可以定义架构以强制实施特定结构。编译器确保对象遵循定义的架构。

var config {
  name: string
  count: int
  enabled: bool
} = {
  name: 'myApp'
  count: 5
  enabled: true
}

以下示例使用具有修饰器的类型化变量来强制实施约束：

@description('The environment to deploy to')
@allowed(['dev', 'test', 'prod'])
param environment string = 'dev'

var instanceCount int = environment == 'prod' ? 5 : 2
var resourcePrefix string = 'app'
var tags {
  environment: string
  deployedBy: string 
} = {
  environment: environment
  deployedBy: 'Bicep'
}

resource storage 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: '${resourcePrefix}storage${instanceCount}'
  ___location: 'westus'
  tags: tags
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

在本示例中：

instanceCount 表现为 int，它使用了条件表达式。
resourcePrefix 类型化为 string.
tags 类型化为具有特定结构的 object。

使用迭代循环

定义变量时，可以使用迭代循环。以下示例将创建具有三种属性的对象数组。

param itemCount int = 3

var objectArray = [for i in range(0, itemCount): {
  name: 'myDataDisk${(i + 1)}'
  diskSizeGB: '1'
  diskIndex: i
}]

output arrayResult array = objectArray

输出返回具有以下值的数组：

[
  {
    "name": "myDataDisk1",
    "diskSizeGB": "1",
    "diskIndex": 0
  },
  {
    "name": "myDataDisk2",
    "diskSizeGB": "1",
    "diskIndex": 1
  },
  {
    "name": "myDataDisk3",
    "diskSizeGB": "1",
    "diskIndex": 2
  }
]

有关可用于变量的循环类型详细信息，请参阅 Bicep 中的迭代循环。

使用修饰器

修饰器是以格式 @expression 编写的，放置在变量声明上方。下表显示了变量的可用修饰器。

修饰器	论点	说明
说明	字符串	提供变量的说明。
导出	无	指示该变量可供另一个 Bicep 文件导入。

修饰器位于 sys 命名空间中。如果需要将修饰器与具有相同名称的其他项区分开来，请在修饰器前面加上 sys。例如，如果 Bicep 文件包含名为 description 的变量，则必须在使用说明修饰器时添加 sys 命名空间。

说明

若要添加解释，请将说明添加到变量声明。例如：

@description('Create a unique storage account name.')
var storageAccountName = uniqueString(resourceGroup().id)

Markdown 格式的文本可用于说明文本。

导出

使用 @export() 来与其他 Bicep 文件共享变量。有关详细信息，请参阅导出变量、类型和函数。

配置变量

可以定义变量来保存配置环境所需的相关值。可以将变量定义为一个包含值的对象。以下示例演示的对象包含的值适用于两个环境 - test 和 prod。在部署过程中传入这些值之一。

@allowed([
  'test'
  'prod'
])
param environmentName string

var environmentSettings = {
  test: {
    instanceSize: 'Small'
    instanceCount: 1
  }
  prod: {
    instanceSize: 'Large'
    instanceCount: 4
  }
}

output instanceSize string = environmentSettings[environmentName].instanceSize
output instanceCount int = environmentSettings[environmentName].instanceCount

后续步骤

若要了解变量的可用属性，请参阅了解 Bicep 文件的结构和语法。
要了解如何使用循环语法，请参阅 Bicep 中的迭代循环。

通过