circleci

用途

CircleCI 是一个云原生 CI/CD 平台，用于构建、测试和部署应用。本技能用于在以下场景提供配置指导：使用 CircleCI 搭建 CI/CD 流水线、使用 orbs 实现可复用配置、通过缓存与并行优化构建时间、配置 CircleCI 工作流与审批、管理 CircleCI 上下文与密钥。

前提条件

CircleCI 账号已连接代码仓库
项目已在 CircleCI 控制台启用
具备基础 YAML 理解能力

配置文件

在项目中创建 .circleci/config.yml，使用 version: 2.1。配置可包含 orbs、executors、jobs 和 workflows。示例中定义了 node 与 docker 两个 orb，一个基于 cimg/node:20.10 的默认执行器，以及 build、test、deploy 三个作业，并通过 build-test-deploy 工作流按顺序执行：build 完成后运行 test，test 完成后仅在 main 分支运行 deploy。

执行器

支持多种执行器类型：

Docker 执行器：可指定多个镜像（如 cimg/node:20.10 与 cimg/postgres:15.0），并设置工作目录。
Machine 执行器：指定镜像（如 ubuntu-2204:current）与资源类（如 large）。
macOS 执行器：指定 Xcode 版本（如 15.0.0）与资源类（如 macos.m1.medium.gen1）。

缓存

支持依赖缓存与多键缓存。依赖缓存通过 restore_cache 与 save_cache 配合，以 package-lock.json 的校验和作为键。多键缓存按分支、校验和、main 分支等顺序回退匹配。

工作区

通过 persist_to_workspace 在作业间持久化数据（如 dist、node_modules），后续作业使用 attach_workspace 挂载。

并行

通过 parallelism 设置并行度，结合 circleci tests glob 与 circleci tests split --split-by=timings 进行测试拆分，并用 store_test_results 存储结果。

工作流

支持顺序作业（通过 requires 声明依赖）、并行作业、手动审批（type: approval）、定时工作流（triggers + schedule + cron 表达式）以及分支与标签过滤（filters）。

Orbs

Orbs 是可复用的配置包。示例中使用 aws-cli 与 kubernetes orb 完成部署。常见 orbs 包括：node、docker、aws-cli、aws-ecr、aws-ecs、gcp-cli、kubernetes、slack。

Docker 构建

使用 docker orb 配合 setup_remote_docker、docker/check、docker/build、docker/push 完成镜像构建与推送，标签可使用 $CIRCLE_SHA1。

环境变量与上下文

项目变量在 CircleCI 项目设置的 Environment Variables 中配置。上下文（contexts）用于按环境（如 staging-secrets、production-secrets）提供密钥。作业步骤中可通过 environment 设置环境变量。

制品与测试结果

使用 store_test_results 存储测试结果，使用 store_artifacts 存储制品（如覆盖率报告）。

资源类

可选资源类包括：small（1 vCPU，2GB RAM）、medium（2 vCPU，4GB RAM，默认）、large（4 vCPU，8GB RAM）、xlarge（8 vCPU，16GB RAM）。

常见问题

缓存未恢复：检查缓存键格式，确认校验和文件未变化。
工作区挂载失败：确认持久化工作区的作业已完成，检查路径。
Docker 层缓存：Docker 构建慢时，可在项目设置中启用 Docker Layer Caching（付费功能）。

最佳实践

使用 orbs 处理常见任务
实施积极的缓存策略
使用工作区在作业间共享数据
通过并行拆分测试以加快构建
使用上下文管理环境相关密钥
定义可复用执行器
存储测试结果以获取洞察

限制

指导内容针对真实环境执行：应用任何变更前需确认目标、影响范围与回滚方案。
未经明确批准，切勿部署到生产环境。
本文档为纯文档导入，上游脚本与模板未随附。
示例片段为独立示例，常省略必需的执行器/安装/报告设置；需结合已安装的 CircleCI schema 验证组合配置，并检查展开后的 orbs。
应固定与当前 runner 兼容的、经过审查的 orb/镜像版本。
密钥上下文/部署作业应限制在受信任分支与已批准身份；审批作业必须同时依赖实际构建产物生产者与测试。
不应允许不受信任的 PR 污染特权缓存/工作区。
应保护/脱敏日志与制品，并在缺少计时/报告数据时说明未运行的测试。

技能介绍

用途