circleci

CircleCI 流水线配置与 CLI

补充说明

CircleCI 用 .circleci/config.yml（2.1 版）描述 job、workflow 和 orb。它提供托管 Runner 和自托管 Runner，本地可用 CLI 校验配置和有限执行。

常用示例

circleci config validate
circleci config process .circleci/config.yml
circleci local execute --job test
circleci pipeline list
circleci workflow list

最小配置：

version: 2.1

orbs:
  node: circleci/node@5.2

jobs:
  test:
    docker:
      - image: cimg/node:20.17
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run: npm test
      - store_artifacts:
          path: coverage

workflows:
  ci:
    jobs:
      - test:
          filters:
            branches:
              only: [main]

易错点与排错

• version: 2.1 才能用 orbs；旧版配置不能直接套用。
• orb 版本和参数要固定；浮动版本会让配置行为随时间变化。
• cimg/* 镜像和旧 circleci/* 镜像的工具集不同；迁移后重新验证。
• 缓存 key 不含 lockfile 哈希会复用过期依赖；用 checksum 参与 key。
• store_artifacts 的路径相对工作目录；路径不存在时任务仍可能成功。
• context 里的密钥受组织/项目权限限制；fork PR 通常拿不到。
• workflow 的 requires 和 filters 共同决定执行图；漏写会导致 job 不跑。
• local execute 只模拟部分环境；依赖 orb、缓存和上下文的步骤不能完整复现。
• Docker-in-Docker 需要 remote Docker 或特权配置；普通 executor 不能直接跑 docker build。

相关命令

• github-actions — GitHub 流水线
• gitlab-ci — GitLab 流水线
• docker — 容器运行时