CircleCI Node.js Docker镜像文档

镜像概述

本Docker镜像专为CircleCI持续集成/持续部署(CI/CD)环境设计，基于Node.js官方镜像优化，提供稳定的Node.js运行环境，旨在简化Node.js应用在CircleCI工作流中的构建、测试和部署流程。镜像预配置了CI环境所需的基础依赖，确保与CircleCI工作流无缝集成。

核心功能与特性

1. 预配置Node.js环境

• 内置稳定版本Node.js及npm/yarn包管理工具
• 支持多版本Node.js（可通过标签指定具体版本）
• 预安装常见Node.js开发依赖（如git、curl、build-essential等）

2. CircleCI环境优化

• 兼容CircleCI工作流语法及执行环境
• 支持CircleCI缓存机制，加速依赖安装过程
• 包含CI环境常用工具（如jq、ssh客户端等）

3. 灵活的版本管理

• 通过镜像标签指定Node.js版本（如:18, :20对应Node.js 18.x、20.x系列）
• 定期更新基础镜像，确保安全补丁及时应用

使用场景

• Node.js项目CI/CD流程：在CircleCI中执行代码 lint、单元测试、集成测试等任务
• Node.js应用打包：构建Node.js应用的生产环境包或Docker镜像
• 依赖管理验证：检查package.json依赖一致性，执行npm audit安全检查
• 多版本兼容性测试：在不同Node.js版本环境中验证应用兼容性

使用方法

基本使用（Docker Run）

# 拉取镜像（指定Node.js 20版本）
docker pull circleci/node:20

# 运行镜像并执行npm测试
docker run -v $(pwd):/app -w /app circleci/node:20 npm test

# 交互式运行，进入容器终端
docker run -it --rm -v $(pwd):/app -w /app circleci/node:20 /bin/bash

Docker Compose配置示例

version: '3'
services:
  node-ci:
    image: circleci/node:20
    volumes:
      - ./:/app
    working_dir: /app
    environment:
      - NODE_ENV=test
      - NPM_CONFIG_LOGLEVEL=silent
    command: npm run ci # 执行项目中的ci脚本（如lint+test）

在CircleCI配置文件中使用

在.circleci/config.yml中引用本镜像作为执行环境：

version: 2.1
jobs:
  build-and-test:
    docker:
      - image: circleci/node:20
    steps:
      - checkout # 拉取代码
      - restore_cache: # 恢复npm依赖缓存
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm ci # 安装依赖
      - save_cache: # 保存依赖缓存
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm run lint # 代码检查
      - run: npm test # 单元测试
      - run: npm run build # 构建应用

workflows:
  version: 2
  main:
    jobs:
      - build-and-test

环境变量说明

注意事项

• 镜像标签格式通常为circleci/node:<node-version>，如:18对应Node.js 18.x，:20.10对应具体小版本
• 建议在CircleCI配置中使用具体版本标签（而非latest）以确保构建稳定性
• 如需自定义依赖或工具，可基于本镜像创建Dockerfile进行二次构建

版本信息

• 支持的Node.js主要版本：14.x, 16.x, 18.x, 20.x
• 镜像定期更新，具体版本信息可参考CircleCI官方镜像仓库