Azure DevOps Pipeline阶段模板嵌套报错及可行性咨询

问题场景 #

主pipeline.yaml调用test-stages.yaml模板，后者多次引入test-stage.yaml模板并传入不同参数（用于多环境部署）。test-stage.yaml定义带参数的阶段时，运行触发Unexpected value 'String'报错，但将嵌套结构展开后可正常运行，需确认该阶段嵌套方案的可行性及报错原因。

涉及的Pipeline文件代码 #

主pipeline.yaml #

trigger:
  - development
pool:
  name: '$(dds-ubuntu-agent)'
name: $(date:MM.dd.yyyy)-$(SERVICE_NAME)-$(Build.SourceBranchName)-$(Build.BuildId)
stages:
  - template: ./test-stages.yaml

test-stages.yaml #

stages:
- template: ./test-stage.yaml
  parameters:
    test: 'asdf'
- template: ./test-stage.yaml
  parameters:
    test: 'qwer'

原test-stage.yaml（报错版本） #

parameters:
- name: test
  type: String

stages:
- stage: ${{ parameters.test }}
  displayName: ${{ parameters.test }}
  jobs:
  - job: ${{ parameters.test }}
    steps:
    - script: echo ${{ parameters.test}}

报错信息 #

/test-stage.yaml (Line: 3, Col: 9): Unexpected value 'String'

原因分析 #

1. 阶段模板的参数语法限制：当在stages节点下引用模板（如test-stages.yaml中引入test-stage.yaml），该模板属于阶段模板，其参数声明语法和普通模板不同——Azure DevOps不允许在阶段模板的parameters里指定type字段，阶段模板的参数默认均为字符串类型，显式声明type: String会触发语法解析错误。
2. 嵌套可行性：多层模板嵌套是完全支持的，报错并非嵌套导致，而是参数声明的语法不符合阶段模板的要求。

解决方案 #

移除test-stage.yaml中参数的type: String声明，修改后的代码如下：

parameters:
- name: test

stages:
- stage: ${{ parameters.test }}
  displayName: ${{ parameters.test }}
  jobs:
  - job: ${{ parameters.test }}
    steps:
    - script: echo ${{ parameters.test}}

若需要给参数设置默认值，可添加default字段，示例：

parameters:
- name: test
  default: 'default-test'

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