circleci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CircleCI

Build, test, and deploy applications using CircleCI's cloud-native CI/CD platform.

使用CircleCI的云原生CI/CD平台构建、测试和部署应用程序。

When to Use This Skill

何时使用此技能

Use this skill when:

Setting up CI/CD pipelines with CircleCI
Using orbs for reusable configuration
Optimizing build times with caching and parallelism
Configuring CircleCI workflows and approvals
Managing CircleCI contexts and secrets

在以下场景使用此技能：

通过CircleCI搭建CI/CD流水线
使用orbs实现可复用配置
通过缓存与并行处理优化构建时长
配置CircleCI工作流与审批流程
管理CircleCI上下文与密钥

Prerequisites

前提条件

CircleCI account connected to repository
Project enabled in CircleCI dashboard
Basic YAML understanding

已连接代码仓库的CircleCI账号
已在CircleCI控制台启用项目
具备基础YAML知识

Configuration File

配置文件

Create

.circleci/config.yml

yaml

version: 2.1

orbs:
  node: circleci/node@5.2
  docker: circleci/docker@2.4

executors:
  default:
    docker:
      - image: cimg/node:20.10
    working_directory: ~/project

jobs:
  build:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Build application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  test:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Run tests
          command: npm test

  deploy:
    executor: default
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Deploy
          command: ./deploy.sh

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

创建

.circleci/config.yml

yaml

version: 2.1

orbs:
  node: circleci/node@5.2
  docker: circleci/docker@2.4

executors:
  default:
    docker:
      - image: cimg/node:20.10
    working_directory: ~/project

jobs:
  build:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Build application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  test:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Run tests
          command: npm test

  deploy:
    executor: default
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Deploy
          command: ./deploy.sh

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

Executors

执行器

Docker Executor

Docker执行器

yaml

executors:
  node:
    docker:
      - image: cimg/node:20.10
      - image: cimg/postgres:15.0
        environment:
          POSTGRES_USER: test
          POSTGRES_DB: testdb
    working_directory: ~/app

yaml

executors:
  node:
    docker:
      - image: cimg/node:20.10
      - image: cimg/postgres:15.0
        environment:
          POSTGRES_USER: test
          POSTGRES_DB: testdb
    working_directory: ~/app

Machine Executor

虚拟机执行器

yaml

executors:
  linux-machine:
    machine:
      image: ubuntu-2204:current
    resource_class: large

yaml

executors:
  linux-machine:
    machine:
      image: ubuntu-2204:current
    resource_class: large

macOS Executor

macOS执行器

yaml

executors:
  macos:
    macos:
      xcode: "15.0.0"
    resource_class: macos.m1.medium.gen1

yaml

executors:
  macos:
    macos:
      xcode: "15.0.0"
    resource_class: macos.m1.medium.gen1

Caching

缓存

Dependency Caching

依赖缓存

yaml

jobs:
  build:
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
            - v1-deps-
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

yaml

jobs:
  build:
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
            - v1-deps-
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

Multi-Key Caching

多键缓存

yaml

- restore_cache:
    keys:
      - v1-{{ .Branch }}-{{ checksum "package-lock.json" }}
      - v1-{{ .Branch }}-
      - v1-main-
      - v1-

yaml

- restore_cache:
    keys:
      - v1-{{ .Branch }}-{{ checksum "package-lock.json" }}
      - v1-{{ .Branch }}-
      - v1-main-
      - v1-

Workspaces

工作区

Persist Data

持久化数据

yaml

jobs:
  build:
    steps:
      - checkout
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

  deploy:
    steps:
      - attach_workspace:
          at: ~/project
      - run: ./deploy.sh

yaml

jobs:
  build:
    steps:
      - checkout
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

  deploy:
    steps:
      - attach_workspace:
          at: ~/project
      - run: ./deploy.sh

Parallelism

并行处理

Test Splitting

测试拆分

yaml

jobs:
  test:
    parallelism: 4
    steps:
      - checkout
      - run:
          name: Run tests
          command: |
            TESTFILES=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
            npm test -- $TESTFILES
      - store_test_results:
          path: test-results

yaml

jobs:
  test:
    parallelism: 4
    steps:
      - checkout
      - run:
          name: Run tests
          command: |
            TESTFILES=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
            npm test -- $TESTFILES
      - store_test_results:
          path: test-results

Workflows

工作流

Sequential Jobs

顺序执行任务

yaml

workflows:
  pipeline:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test

yaml

workflows:
  pipeline:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test

Parallel Jobs

并行执行任务

yaml

workflows:
  pipeline:
    jobs:
      - build
      - test-unit:
          requires:
            - build
      - test-integration:
          requires:
            - build
      - deploy:
          requires:
            - test-unit
            - test-integration

yaml

workflows:
  pipeline:
    jobs:
      - build
      - test-unit:
          requires:
            - build
      - test-integration:
          requires:
            - build
      - deploy:
          requires:
            - test-unit
            - test-integration

Manual Approval

手动审批

yaml

workflows:
  deploy-prod:
    jobs:
      - build
      - test
      - hold:
          type: approval
          requires:
            - test
      - deploy-production:
          requires:
            - hold

yaml

workflows:
  deploy-prod:
    jobs:
      - build
      - test
      - hold:
          type: approval
          requires:
            - test
      - deploy-production:
          requires:
            - hold

Scheduled Workflows

定时工作流

yaml

workflows:
  nightly:
    triggers:
      - schedule:
          cron: "0 2 * * *"
          filters:
            branches:
              only:
                - main
    jobs:
      - build
      - test

yaml

workflows:
  nightly:
    triggers:
      - schedule:
          cron: "0 2 * * *"
          filters:
            branches:
              only:
                - main
    jobs:
      - build
      - test

Branch Filtering

分支过滤

yaml

workflows:
  build-deploy:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main
                - /feature-.*/
      - deploy:
          filters:
            branches:
              only: main
            tags:
              only: /^v.*/

yaml

workflows:
  build-deploy:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main
                - /feature-.*/
      - deploy:
          filters:
            branches:
              only: main
            tags:
              only: /^v.*/

Orbs

Using Orbs

使用Orbs

yaml

version: 2.1

orbs:
  aws-cli: circleci/aws-cli@4.1
  kubernetes: circleci/kubernetes@1.3

jobs:
  deploy:
    executor: aws-cli/default
    steps:
      - aws-cli/setup:
          aws_access_key_id: AWS_ACCESS_KEY_ID
          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      - kubernetes/install-kubectl
      - run: kubectl apply -f k8s/

yaml

version: 2.1

orbs:
  aws-cli: circleci/aws-cli@4.1
  kubernetes: circleci/kubernetes@1.3

jobs:
  deploy:
    executor: aws-cli/default
    steps:
      - aws-cli/setup:
          aws_access_key_id: AWS_ACCESS_KEY_ID
          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      - kubernetes/install-kubectl
      - run: kubectl apply -f k8s/

Common Orbs

常用Orbs

yaml

orbs:
  node: circleci/node@5.2              # Node.js
  docker: circleci/docker@2.4          # Docker builds
  aws-cli: circleci/aws-cli@4.1        # AWS CLI
  aws-ecr: circleci/aws-ecr@9.0        # ECR push
  aws-ecs: circleci/aws-ecs@4.0        # ECS deploy
  gcp-cli: circleci/gcp-cli@3.1        # GCP CLI
  kubernetes: circleci/kubernetes@1.3  # K8s deploy
  slack: circleci/slack@4.12           # Notifications

yaml

orbs:
  node: circleci/node@5.2              # Node.js
  docker: circleci/docker@2.4          # Docker构建
  aws-cli: circleci/aws-cli@4.1        # AWS CLI
  aws-ecr: circleci/aws-ecr@9.0        # ECR推送
  aws-ecs: circleci/aws-ecs@4.0        # ECS部署
  gcp-cli: circleci/gcp-cli@3.1        # GCP CLI
  kubernetes: circleci/kubernetes@1.3  # K8s部署
  slack: circleci/slack@4.12           # 通知

Docker Builds

Docker构建

yaml

version: 2.1

orbs:
  docker: circleci/docker@2.4

jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker:
          version: 20.10.24
      - checkout
      - docker/check
      - docker/build:
          image: myorg/myapp
          tag: $CIRCLE_SHA1
      - docker/push:
          image: myorg/myapp
          tag: $CIRCLE_SHA1

yaml

version: 2.1

orbs:
  docker: circleci/docker@2.4

jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker:
          version: 20.10.24
      - checkout
      - docker/check
      - docker/build:
          image: myorg/myapp
          tag: $CIRCLE_SHA1
      - docker/push:
          image: myorg/myapp
          tag: $CIRCLE_SHA1

Environment Variables

环境变量

Project Variables

项目变量

Set in CircleCI Project Settings > Environment Variables

在CircleCI项目设置 > 环境变量中配置

Contexts

上下文

yaml

workflows:
  deploy:
    jobs:
      - deploy-staging:
          context: staging-secrets
      - deploy-production:
          context: production-secrets

yaml

workflows:
  deploy:
    jobs:
      - deploy-staging:
          context: staging-secrets
      - deploy-production:
          context: production-secrets

Using Variables

使用变量

yaml

jobs:
  deploy:
    steps:
      - run:
          name: Deploy
          command: |
            aws s3 sync dist/ s3://$S3_BUCKET
          environment:
            AWS_DEFAULT_REGION: us-east-1

yaml

jobs:
  deploy:
    steps:
      - run:
          name: Deploy
          command: |
            aws s3 sync dist/ s3://$S3_BUCKET
          environment:
            AWS_DEFAULT_REGION: us-east-1

Artifacts and Test Results

制品与测试结果

yaml

jobs:
  test:
    steps:
      - run:
          name: Run tests
          command: npm test -- --coverage
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: coverage
          destination: coverage-report

yaml

jobs:
  test:
    steps:
      - run:
          name: Run tests
          command: npm test -- --coverage
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: coverage
          destination: coverage-report

Resource Classes

资源类

yaml

jobs:
  build:
    docker:
      - image: cimg/node:20.10
    resource_class: large  # 4 vCPU, 8GB RAM
    steps:
      - checkout
      - run: npm run build

yaml

jobs:
  build:
    docker:
      - image: cimg/node:20.10
    resource_class: large  # 4 vCPU, 8GB RAM
    steps:
      - checkout
      - run: npm run build

Available classes:

可用资源类:

small: 1 vCPU, 2GB RAM

medium: 2 vCPU, 4GB RAM (default)

medium: 2 vCPU, 4GB RAM (默认)

large: 4 vCPU, 8GB RAM

xlarge: 8 vCPU, 16GB RAM

undefined

undefined

Common Issues

常见问题

Issue: Cache Not Restoring

问题：缓存未恢复

Problem: Cache misses on every build Solution: Verify cache key format, ensure checksum file hasn't changed

现象：每次构建都出现缓存未命中 解决方案：验证缓存键格式，确保校验文件未变更

Issue: Workspace Attach Fails

问题：工作区挂载失败

Problem: Cannot find persisted workspace Solution: Ensure persist_to_workspace job completed, check paths

现象：无法找到持久化的工作区 解决方案：确认persist_to_workspace任务已完成，检查路径配置

Issue: Docker Layer Caching

问题：Docker层缓存失效

Problem: Docker builds are slow Solution: Enable Docker Layer Caching in project settings (paid feature)

现象：Docker构建速度缓慢 解决方案：在项目设置中启用Docker层缓存（付费功能）

Best Practices

最佳实践

Use orbs for common tasks
Implement aggressive caching strategies
Use workspaces for sharing data between jobs
Split tests with parallelism for faster builds
Use contexts for environment-specific secrets
Define reusable executors
Store test results for insights

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