环境变量

内置变量使用限制

使用内置变量时，注意以下限制和特殊场景：

• 多代码源变量歧义风险：当流水线配置了多个代码源时，不要直接使用无下标的 CI_COMMIT_REF_NAME、CI_COMMIT_SHA 等变量。虽然系统默认取第一个代码源的值，但结果不可预期。应始终使用带数字后缀的变量（如 CI_COMMIT_REF_NAME_1、CI_COMMIT_REF_NAME_2）明确指定代码源。

• Git 变量获取前提：CI_COMMIT_TITLE、CI_COMMIT_SHA、CI_COMMIT_ID 等 Git 相关内置变量，必须在流水线中添加"获取代码"步骤后才能获取到值。若流水线未配置代码拉取步骤，这些变量将为空。

• 变量处理限制：云效流水线不支持对系统内置变量（如 CI_COMMIT_ID）直接进行字符串截取、正则提取等函数处理。如需对变量值进行加工，在 Shell 脚本中先将其赋值给自定义变量，再对自定义变量进行操作。示例如下：

  # 将内置变量赋值给自定义变量后再处理
  MY_SHORT_ID=$(echo $CI_COMMIT_ID | cut -c1-8)
  echo "MY_SHORT_ID=$MY_SHORT_ID" >> "$FLOW_ENV"

• CI_WORKSPACE 适用范围：CI_WORKSPACE 仅在当前构建环境有效。在主机部署（ECS）场景中，该变量可能无效或指向非预期路径，不要依赖此变量定位 ECS 上的文件。

• 缺失变量说明：内置变量不包含"当前仓库项目名"或"完整 Git 地址"。如需这些信息，可通过自定义变量手动配置，或结合 Codeup 域名自行拼接 Git 仓库地址。

字符变量

1. 在流水线变量和缓存 > 字符变量处，单击 新建变量，打开新建变量弹窗。

2. 输入变量名称和默认值，可以设置私密模式和运行时设置。

   1. 变量名称：注意环境变量名称不可使用横杠符号 - 。

   2. 私密模式：控制变量是否对外公开。当变量设置为私密模式后，将无法查看变量的值，相应的执行日志中也不会显示。通常适用于用户名，密码等私密信息场景。

   3. 运行时设置：控制变量值是否需要在流水线运行时设置。当变量设置为运行时设置后，流水线运行时需要设置变量的值。通常适用于需要动态配置流水线参数值场景。

3. 可以添加更多变量，也可以删除变量。

4. 单击添加后，需要保存流水线才可以将变量保存至流水线。保存完毕后即可按场景 使用环境变量。

运行选择变量

1. 在流水线变量和缓存 > 运行选择变量处，单击 新建变量，打开新建变量弹窗。

2. 输入变量名称和选项。

   1. 单击添加选项可以为变量取值添加多个选项。

   2. 选项打开默认值则该选项为该变量的默认取值。

3. 单击添加后，需要保存流水线才可以将变量保存至流水线。保存完毕后即可按场景 使用环境变量。

4. 在流水线点击运行时需要选择变量取值。

自定义变量最佳实践

• 命名冲突规避：自定义变量名应避免与系统预置变量名或常见构建参数冲突。例如，image、tag 等变量名可能与镜像构建步骤的内置参数冲突，导致构建步骤报错或行为异常。建议为自定义变量添加业务前缀（如 APP_IMAGE、DEPLOY_TAG）以避免冲突。变量命名规则：以字母开头，仅支持大小写字母、数字和下划线（_），长度 1~64 个字符，且不允许与预置变量名重复。

• 特殊字符转义：当变量值包含 @、#、& 等特殊字符时（如用户名或密码），直接在 URL 中拼接会导致格式错误。例如，密码 pass@123 在 URL https://user:pass@123@host 中会被错误解析。建议采用以下方案之一：

  • 对特殊字符进行 URL 编码（如 @ 转为 %40），将 pass@123 编码为 pass%40123。

  • 使用凭据管理或将变量设为私密模式，由系统自动处理认证信息，避免手动拼接。

• 动态代码源权限：流水线不支持自动以执行者身份登录动态代码仓库。如需在流水线中访问非预配置的代码仓库，建议将 Git 账号和个人访问令牌（Token）配置为私密变量，在脚本中通过变量引用完成认证；或使用流水线代码源配置方式获取代码权限。

• YAML 变量转义：在 kubectl apply 等场景中，YAML 文件中的 ${} 语法会被流水线引擎误识别为流水线变量并进行替换。解决方案：

  • 在流水线步骤配置中勾选变量校验选项，禁用自动变量解析。

  • 使用转义语法 $${变量名} 保留原始字符串。例如，YAML 中需要保留 ${2} 时，在流水线配置中写为 $${2}。

任务间环境变量传递

这种场景主要是流水线内多个任务节点的环境变量共享，比如任务一生成变量 yaojia_Test=myParam，任务二通过 ${yaojia_Test} 引用。

• 您可以在任务一的步骤中通过将环境变量输出到$FLOW_ENV中完成环境变量注入。

• 在任务一中，将环境变量设置为流水线级别的环境变量。

• 在任务二中通过 ${yaojia_Test} 使用该环境变量。

任务一完成变量注入和提升后，任务二即可通过 ${yaojia_Test} 引用。

# 任务二执行日志
echo $yaojia_Test
myParam
# [Success]