CircleCI Executor 镜像文档

一、镜像概述和主要用途

CircleCI Executor 镜像是用于 CircleCI 持续集成/持续部署 (CI/CD) 平台的专用执行环境镜像。该镜像旨在为开发者提供标准化、预配置的运行环境，简化 CircleCI 作业（Job）的配置流程，确保构建、测试、部署等 CI/CD 环节在一致性环境中高效执行。

主要用途：

• 作为 CircleCI 作业的基础运行容器，提供操作系统及开发工具链
• 支持多语言、多框架项目的自动化构建与测试流程
• 减少环境配置复杂度，提升 CI/CD 流水线的稳定性与可重复性

二、核心功能和特性

2.1 预配置环境

• 基于主流操作系统（如 Ubuntu LTS）构建，确保兼容性
• 预装常用开发工具：Git、Docker、Docker Compose、curl、wget、make 等
• 集成多语言运行时（根据镜像标签，支持 Node.js、Python、Java、Ruby、Go 等）

2.2 版本化与兼容性

• 采用语义化版本控制（如 2.0-ubuntu-22.04），支持精确环境锁定
• 定期更新基础镜像及工具链，同步安全补丁与功能升级
• 与 CircleCI 平台全版本兼容，支持 Workflows、Caching、Artifacts 等核心功能

2.3 可扩展性与集成能力

• 支持通过 Dockerfile 或 CircleCI 配置扩展工具链，按需安装额外依赖
• 内置 CircleCI 代理（Agent），实现与平台日志、状态同步的深度集成
• 兼容 CircleCI 缓存机制，支持依赖缓存（如 npm、Maven 依赖）以加速作业执行

三、使用场景和适用范围

3.1 适用项目类型

• Web 应用（前端/后端服务、API 接口）
• 移动应用（Android/iOS 构建，需配合对应 SDK）
• 开源项目（自动化测试、版本发布）
• 企业级应用（多环境部署、合规性构建）

3.2 典型应用场景

• 自动化构建：拉取代码后自动执行编译、打包（如 npm run build、mvn package）
• 多阶段测试：在隔离环境中运行单元测试、集成测试、E2E 测试
• 持续部署：测试通过后自动推送镜像至仓库或部署至云服务
• 本地环境模拟：开发者可本地运行容器复现 CircleCI 环境，调试 CI 配置问题

四、详细使用方法和配置说明

4.1 在 CircleCI 配置中使用

4.1.1 基础配置（.circleci/config.yml）

在 CircleCI 配置文件中通过 executor 指定镜像，示例如下：

version: 2.1

executors:
  # 定义自定义执行器
  app-executor:
    docker:
      - image: circleci/executor:node-18-ubuntu-22.04  # 镜像名称:标签

jobs:
  build-test:
    executor: app-executor  # 使用自定义执行器
    steps:
      - checkout  # 拉取代码
      - run: npm install  # 安装依赖
      - run: npm test     # 执行测试
      - run: npm run build  # 构建项目

workflows:
  main:
    jobs:
      - build-test

4.1.2 语言环境指定

通过镜像标签选择特定语言版本，例如：

• circleci/executor:python-3.11-ubuntu-22.04（Python 3.11 环境）
• circleci/executor:java-17-ubuntu-20.04（Java 17 环境，Ubuntu 20.04 基础）

4.2 本地调试与使用

4.2.1 拉取镜像

docker pull circleci/executor:<标签>  # 例如 docker pull circleci/executor:node-18-ubuntu-22.04

4.2.2 启动本地容器（模拟 CircleCI 环境）

docker run -it --rm \
  -v $(pwd):/home/circleci/project \  # 挂载本地项目至容器工作区
  -w /home/circleci/project \         # 设置工作目录
  circleci/executor:node-18-ubuntu-22.04 \
  /bin/bash  # 启动交互式终端

进入容器后，可直接执行项目命令（如 npm test），模拟 CircleCI 作业流程。

4.3 环境变量与配置参数

4.3.1 内置环境变量

镜像默认设置以下环境变量，可直接在作业中使用：

• CIRCLE_WORKING_DIRECTORY：默认工作目录（/home/circleci/project）
• CIRCLE_CACHE_DIR：缓存目录（/home/circleci/.cache，用于 CircleCI 缓存功能）
• LANG：默认语言环境（en_US.UTF-8）

4.3.2 自定义环境变量

在 CircleCI 作业中通过 environment 字段添加自定义变量：

jobs:
  build-test:
    executor: app-executor
    environment:
      NODE_ENV: production
      BUILD_OUTPUT: ./dist
    steps:
      - run: npm run build -- --output=$BUILD_OUTPUT  # 使用自定义变量

五、Docker 部署方案示例

5.1 CircleCI 完整配置示例（.circleci/config.yml）

version: 2.1

executors:
  node-executor:
    docker:
      - image: circleci/executor:node-18-ubuntu-22.04
    resource_class: medium  # 配置资源规格（CPU/内存）

jobs:
  test:
    executor: node-executor
    steps:
      - checkout
      - restore_cache:  # 恢复 npm 依赖缓存
          keys:
            - npm-v1-{{ checksum "package-lock.json" }}
      - run: npm install
      - save_cache:  # 保存 npm 依赖缓存
          paths: [node_modules]
          key: npm-v1-{{ checksum "package-lock.json" }}
      - run: npm test  # 执行测试
      - store_test_results:  # 存储测试结果
          path: ./test-results

  build:
    executor: node-executor
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-v1-{{ checksum "package-lock.json" }}
      - run: npm install
      - run: npm run build
      - store_artifacts:  # 存储构建产物
          path: ./dist

workflows:
  ci-pipeline:
    jobs:
      - test
      - build:
          requires: [test]  # 依赖 test 作业成功后执行

5.2 本地调试容器启动命令

# 拉取镜像
docker pull circleci/executor:node-18-ubuntu-22.04

# 启动容器并挂载项目目录
docker run -it --rm \
  -v $(pwd):/home/circleci/project \
  -w /home/circleci/project \
  -e NODE_ENV=development \
  circleci/executor:node-18-ubuntu-22.04 \
  /bin/bash

六、注意事项

1. 镜像标签选择：避免使用 latest 标签，建议指定具体版本（如 node-18-ubuntu-22.04）以确保环境稳定性。
2. 资源配置：根据作业需求调整 resource_class（如 large 用于高资源消耗任务）。
3. 缓存优化：合理使用 restore_cache/save_cache 减少重复依赖安装时间。
4. 安全更新：定期同步镜像版本，获取基础镜像及工具链的安全补丁。