sentisis/circleci-node

NodeJS CircleCI专用镜像文档

镜像概述

本镜像专为CircleCI持续集成/持续部署(CI/CD)作业设计，基于官方NodeJS镜像构建，集成了CircleCI环境所需的预配置文件和辅助脚本。旨在简化NodeJS项目在CircleCI流程中的环境准备工作，减少重复配置，提升CI/CD效率。

核心功能与特性

1. 预配置NodeJS环境

• 基于官方NodeJS镜像稳定版本构建，确保环境一致性
• 预安装常用依赖管理工具（npm、yarn、pnpm），支持多种包管理方式
• 内置NodeJS版本切换能力（部分标签支持多版本选择）

2. CircleCI兼容配置

• 包含CircleCIRunner所需的用户权限配置（非root用户运行，符合安全最佳实践）
• 预配置缓存目录（如node_modules缓存路径），优化依赖安装速度
• 集成CircleCI Artifacts路径配置，简化测试报告、构建产物的收集流程

3. 辅助脚本集

• ci-install-deps：加速依赖安装脚本，支持依赖缓存检测与复用
• ci-run-tests：标准化测试执行流程，自动生成CircleCI兼容的测试报告
• ci-build-project：封装构建逻辑，支持自定义构建命令注入
• ci-cleanup：作业结束后清理临时文件，减少磁盘空间占用

4. 轻量级优化

• 移除非必要系统依赖，镜像体积较基础镜像减少约20%
• 采用多阶段构建策略，仅保留运行时必需文件
• 支持--slim标签变体，进一步缩减镜像大小（适用于资源受限环境）

使用场景与适用范围

• NodeJS项目的CircleCI流水线：前端项目（React、Vue、Angular等）、后端服务（Express、NestJS、Koa等）
• 自动化任务执行：代码 lint 检查、单元测试、集成测试、构建打包、版本发布等流程
• 多环境一致性保障：确保开发、测试、CI环境中NodeJS版本及依赖管理工具的一致性
• CI/CD流程简化：适用于希望减少CircleCI配置文件复杂度的团队

使用方法与配置说明

1. 获取镜像

镜像通常托管于私有仓库（如公司内部Docker Registry）或Docker Hub，通过标签指定NodeJS版本：

bash
# 拉取指定版本（例如NodeJS 18.x）
docker pull docker.xuanyuan.run/[仓库地址]/nodejs-circleci:18
# 拉取轻量版本
docker pull docker.xuanyuan.run/[仓库地址]/nodejs-circleci:18-slim

2. 基本使用示例

本地测试（模拟CircleCI环境）

bash
# 挂载项目目录并运行测试脚本
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/[仓库地址]/nodejs-circleci:18 \
  sh -c "./ci-install-deps && ./ci-run-tests"

CircleCI配置文件中引用

在.circleci/config.yml中指定本镜像作为作业执行环境：

yaml
version: 2.1
jobs:
  test:
    docker:
      - image: [仓库地址]/nodejs-circleci:18  # 使用本镜像
    steps:
      - checkout  # 拉取代码
      - run: ci-install-deps  # 使用内置脚本安装依赖
      - run: ci-run-tests     # 使用内置脚本执行测试
      - store_test_results:  # 收集测试报告（依赖预配置的Artifacts路径）
          path: test-results

3. 环境变量配置

通过环境变量自定义镜像行为：

配置示例（CircleCI中设置环境变量）

yaml
jobs:
  build:
    docker:
      - image: [仓库地址]/nodejs-circleci:18
        environment:
          NPM_REGISTRY: "https://registry.npm.taobao.org"  # 使用淘宝npm镜像
          DEPENDENCY_CACHE: "true"
    steps:
      - checkout
      - run: ci-install-deps  # 将使用自定义npm仓库安装依赖

4. 辅助脚本详细说明

ci-install-deps

• 功能：安装项目依赖，支持npm、yarn、pnpm自动检测
• 缓存逻辑：检查package-lock.json/yarn.lock/pnpm-lock.yaml哈希，命中缓存时直接复用node_modules
• 使用示例：

  bash
  ci-install-deps  # 自动检测包管理器并安装依赖
  

ci-run-tests

• 功能：执行项目测试命令，生成JUnit格式测试报告
• 支持参数：--coverage（生成覆盖率报告）、--verbose（详细日志）
• 使用示例：

  bash
  ci-run-tests --coverage  # 执行测试并生成覆盖率报告
  

ci-build-project

• 功能：执行项目构建命令，支持自定义构建脚本
• 环境变量注入：BUILD_CMD（自定义构建命令，默认读取package.json的build脚本）
• 使用示例：

  bash
  BUILD_CMD="npm run build:prod" ci-build-project  # 自定义构建命令
  

5. 版本标签说明

镜像通过标签区分NodeJS版本及特性：

注意事项

• 私有仓库访问：使用前需确保CircleCI Runner有权限拉取镜像（配置Docker Registry凭证）
• 版本兼容性：不同NodeJS版本的镜像可能存在依赖工具差异，建议根据项目NodeJS版本选择对应镜像标签
• 自定义需求：如需扩展功能，可基于本镜像创建Dockerfile进行二次构建（例如添加项目特定依赖）
• 脚本更新：辅助脚本可能随镜像版本更新，建议定期同步镜像以获取最新功能和修复

维护与支持

• 镜像更新周期：跟随NodeJS官方LTS版本更新，每月进行安全补丁更新
• 问题反馈：通过内部DevOps工单系统提交镜像相关问题
• 文档更新：最新使用说明及变更记录请参考项目内部Wiki