配置 Bicep 编译器版本需求

使用 bicepconfig.json 中的 bicep.version 属性来声明你的 Bicep 文件支持哪些编译器版本。 你可以要求一个精确版本,或者允许指定版本范围,帮助团队保持本地开发和自动化构建的一致性。

版本固定会检查已经在运行的编译器。 该设置本身不会下载、安装或切换编译器版本。

设置编译器版本要求

在你的bicep中添加一个部分:

{
  "bicep": {
    "version": "1.2.3"
  }
}

该示例仅允许版本 1.2.3。 若要改为指定范围,请使用比较运算符:

{
  "bicep": {
    "version": ">=1.2.0, <2.0.0"
  }
}

该范围允许版本大于等于 1.2.0 且小于 2.0.0。

本文中的版本号展示了语法格式。 它们不是最低支持版本,也不表示这些版本可用。 选择支持该功能和您的 Bicep 文件的已发布编译器版本。

如果未配置生效的版本要求,Bicep 就不会进行这个版本检查。 添加要求不会更改模板的资源 API 版本或固定模块注册表版本。

支持的版本语法

一个版本包含一个、两个或三个数字组成部分:主版本号、次版本号和补丁版本号。 Bicep按这个顺序对组件进行数值比较。 例如,1.10.0 大于 1.2.0。

Syntax Meaning
1.2.3 或 =1.2.3 没 1.2.3错。
>1.2.3 大于 1.2.3,不包括该版本。
>=1.2.3 大于或等于 1.2.3。
<2.0.0 低于 2.0.0,不包括该版本。
<=2.0.0 小于或等于 2.0.0。
>=1.2.0, <2.0.0 两个条件都必须满足。

一个二条件范围必须包含一个下界(> 或 >=)和一个上界(< 或 <=)。 用逗号分隔。 任一顺序均可接受:<2.0.0, >=1.2.0 与 >=1.2.0, <2.0.0 含义相同。 条件周围以及算符与其版本之间的空格是被接受的。

简短版是精确的,不是通配符

缺失组件默认为零:

价值 等效值
1 1.0.0
1.2 1.2.0
>=1.2, <2 >=1.2.0, <2.0.0

尤其是,"1.2" 并不允许所有 1.2 补丁版本。 要允许该范围,写成 ">=1.2.0, <1.3.0"。

不支持的语法

Bicep 使用自己的数值版本约束语法。 不要假设包管理器接受的表达式在这里也能用。

不受支持的格式 Examples
Wildcards *、1.*、1.2.x
插入符或波浪号范围 ^1.2.3、~1.2.3
可选条件或不等条件 1.2.3 || 2.0.0、!=1.2.3
连字符或区间范围 1.2.0 - 2.0.0、[1.2.0,2.0.0)
版本前缀 v1.2.3
约束中的预发布版本或构建元数据 1.2.3-preview、1.2.3+build
重复的下界或上界 >=1.0.0, >=1.2.0
一个精确版本加上另一个条件 =1.2.3, <2.0.0
超过两个条件 >=1.0.0, <2.0.0, <=1.9.0
前置零或超过三个分量 01.2.3、1.2.3.4
空字符串 ""

不支持的 bicep.version 表达式会导致 Bicep 报告 BCP273,即针对无效 Bicep 配置文件显示的现有错误。 这个诊断并非版本约束特有。 例如,"version": "^1.2.3" 会生成一条带有配置级上下文的消息,后跟具体原因:

BCP273: Failed to parse the contents of the Bicep configuration file "file:///example/bicepconfig.json": The bicep.version property "^1.2.3" is not a valid Bicep version or version range.

在这种情况下,即使版本表达式不受支持,JSON也可以是有效的。 修正 bicep.version 数值。

一个区间可以有有效的语法,但不匹配任何版本号。 例如,>=2.0.0, <1.0.0 可以被解析,但没有任何数字形式的编译器版本满足它。 同样,没有哪个版本严格介于 1.2.3 和 1.2.4之间。 有效的语法也不保证存在匹配的 Bicep 发布。

理解CLI和编辑器的行为

编译器会将其运行版本与每个源文件的有效要求进行比对。

条件 Bicep CLI(命令行界面) 编辑器中的Bicep语言服务器
运行版本满足该要求 没有版本不匹配诊断信息。 没有版本不匹配的提示。
运行版本不满足这个要求 BCP456 是阻止成功编译的错误。 BCP456,警告。
当前运行版本无法解析,因此无法进行比较 BCP457,一个警告。 BCP457,警告。
配置需求无效 BCP273,一个配置错误。 BCP273,一个配置错误。

编辑器警告并不意味着同一文件在使用不兼容的 CLI 时也能成功构建。 警告允许你继续编辑,但你仍然需要兼容的编译器来构建。

BCP457意味着该要求无法被检查,并不表示该要求已通过。 其他编译器错误和 linter 诊断仍然适用,无论版本检查结果如何。

跨文件夹和模块使用版本要求

每个 .bicep 或 .bicepparam 文件都会找到自己最近的 bicepconfig.json文件,从源文件的文件夹开始搜索父文件夹。 发现并不是从你shell当前的文件夹开始的。

本地模块使用自身的最近配置,而不是父模块已解析的设置。 一个编译器负责编译,因此该编译器必须满足所有适用要求。 Bicep 不会为每个模块选择不同的可执行文件。

例如:

project\
  bicepconfig.json
  main.bicep
  modules\
    bicepconfig.json
    storage.bicep

如果根配置需要 >=1.0.0, <2.0.0 ,模块配置要求 >=1.5.0, <2.0.0,则版本 >=1.5.0, <2.0.0 满足两者。 然而,入口点仍允许那些被模块拒绝的旧版本。

两条新的 lint 规则有助于识别这些差异:

规则 默认级别 检查内容
no-conflicting-version-constraints Error 入口点及其本地模块是否有共同允许的版本。
no-incompatible-entrypoint-version Warning 入口点允许的每个版本是否也被每个受约束的本地模块允许。

这些是不同的检查项。 重叠的范围可以通过冲突规则,但不通过入口点兼容性规则,如前述例子所示。 将根依赖要求缩小到 >=1.5.0, <2.0.0 可解决这种不兼容。

规则遵循直接且传递的局部 module 引用。 它们不会扫描你仓库中的每个文件,也不会检查注册表和模板规范模块的内部结构。 它们不是对 import 或 .bicepparamusing 引用的通用遍历。 每条规则报告其在入口点文档起点的第一个发现,并使用该入口点的有效规则设置。

如果入口点没有要求,但本地模块有,入口点兼容性规则会警告:该入口点可能会允许模块拒绝的编译器。 没有要求的模块不会增加任何限制。

继承共享需求

父级文件夹配置文件不会自动合并。 为了共享设置同时保持更接近的配置,可以使用 配置继承。

例如,创建 shared\bicepconfig.json:

{
  "bicep": {
    "version": ">=1.2.0, <2.0.0"
  }
}

在 app\bicepconfig.json中,扩展该文件:

{
  "extends": "../shared/bicepconfig.json"
}

应用继承了共享的要求。 如果应用提供了自己的非空bicep.version字符串,该字符串将替换继承的要求;Bicep 不会对这两个字符串求交集:

{
  "extends": "../shared/bicepconfig.json",
  "bicep": {
    "version": "1.5.0"
  }
}

有效要求恰好是 1.5.0。 省略该属性会保留继承的值。 将其设置为 null 不会清除继承的非空要求。 要移除继承需求,可以更改基础配置或继承结构。

试试版本检查

以下步骤使用独立的 Bicep CLI,而非 Azure CLI 或 Azure PowerShell。

  1. 检查你直接调用的编译器:

    bicep --version
    
  2. 在测试文件旁边创建一个 bicepconfig.json 文件,将 bicep.version 设置为已安装编译器报告的数字版本。 编译器必须支持该配置设置。

  3. 创建 main.bicep:

    output message string = 'Version requirement example'
    
  4. 编译该文件:

    bicep build .\main.bicep
    

    匹配的版本不会产生 BCP456 诊断信息。 输出为 main.json.

  5. 把已配置的要求项改成排除你正在运行的版本,然后再重新运行构建。

    构建过程将 BCP456 报告为错误。 当编辑器的语言服务器编译器不满足要求时,会报告BCP456作为警告。

检查报告该诊断的工具所用的编译器。 你的编辑器和命令行工具可以使用不同的 Bicep 安装版本。 bicep --version 命令描述的是该命令解析到的可执行文件,而不是你电脑上的所有工具。

配置兼容性规则

使用现有的 linter 配置 来更改每条规则的等级:

{
  "analyzers": {
    "core": {
      "rules": {
        "no-conflicting-version-constraints": {
          "level": "error"
        },
        "no-incompatible-entrypoint-version": {
          "level": "warning"
        }
      }
    }
  }
}

支持水平为 error、 warning、 info和 off。 这些设置控制了两条兼容性规则的严重程度。

版本要求疑难解答

诊断或症状 Action
BCP273 请查看详细配置错误信息。 如果识别 bicep.version为某个版本约束,则通过使用支持的数值版本或范围来纠正约束。 BCP273 还可以报告其他配置问题。
BCP456 使用满足该要求的编译器,或者在检查兼容性后有意更新该要求。 请阅读消息以查找其声明配置。
BCP457 使用其报告版本能够被解析的编译器。 不要把警告当作一次成功的兼容性检查。
版本约束冲突 将入口点和本地模块需求对齐,使得存在一个通用版本。
不兼容的入口点要求 缩小入口点的范围,或者在验证兼容性后更新模块需求,确保所有允许的入口点版本都与模块兼容。
编辑和CLI意见不合 检查每个工具使用的编译器版本以及相关文件的就近配置。

如果约束冲突,单靠安装另一个编译器无法解决问题:没有单一版本满足所有要求。