CircleCI分支与标签条件语句失效：流水线未触发问题排查

AI 小北

2026-8-18

问题分析与解决方案

核心问题1：未配置Tag触发权限

CircleCI默认不会对Git Tag推送触发流水线，因为默认的filters规则会忽略所有Tag。你的when条件即使逻辑正确，流水线也根本不会启动——因为Tag推送被默认过滤掉了。

核心问题2：条件缺失部分规则

你的需求是Tag匹配/^(patch\/)?v.*/ 或 /^hotfix-.*/，但当前配置只实现了前者，缺少后者的匹配规则。

额外优化点：正则表达式的YAML解析问题

未用引号包裹正则表达式字符串，可能导致YAML解析时出现异常（比如斜杠被误解析为特殊符号），建议用单引号或双引号包裹。

修正后的配置方案

方案1：使用`filters`直接配置触发规则（更简洁推荐）

直接在Workflow的Job规则里配置分支和Tag的触发条件，无需额外when语句：

workflows:
  # 替换为你的Workflow名称
  your-workflow-name:
    jobs:
      # 替换为你的Job名称
      your-job-name:
        filters:
          branches:
            only: master
          tags:
            only: /^(patch\/)?v.*|^hotfix-.*/

方案2：结合`when`条件与`filters`

如果需要更复杂的逻辑判断，可保留when条件，但必须同时配置filters允许Tag触发：

workflows:
  your-workflow-name:
    jobs:
      your-job-name:
        filters:
          # 允许所有Tag触发，后续通过when条件过滤
          tags:
            only: /.*/
          # 仅允许master分支触发
          branches:
            only: master
        when:
          condition:
            or:
              - equal: ["master", << pipeline.git.branch >>]
              - matches:
                  pattern: '/^(patch\/)?v.*/'
                  value: << pipeline.git.tag >>
              - matches:
                  pattern: '/^hotfix-.*/'
                  value: << pipeline.git.tag >>