bluebite/circleci-node

circleci-dockerfiles 镜像文档

镜像概述

circleci-dockerfiles是为CircleCI持续集成/持续部署(CI/CD)平台构建的自定义Docker镜像，基于Node.js环境，旨在简化Node.js项目在CircleCI中的自动化构建、测试及部署流程。该镜像整合了CircleCI运行所需的核心工具与Node.js运行环境，提供开箱即用的CI/CD支持。

核心功能与特性

• Node.js环境支持：预安装指定版本的Node.js及包管理工具（npm/yarn），满足不同Node.js项目的运行需求。
• CircleCI工具集成：内置CircleCI运行时依赖（如git、curl、ssh等），确保与CircleCI平台无缝对接。
• 自定义配置灵活性：支持通过Dockerfile或环境变量调整镜像参数（如Node.js版本、依赖库版本等），适配多样化项目需求。
• 轻量级设计：基于官方Node.js slim镜像构建，减少镜像体积，提升CI/CD流程执行效率。

使用场景

• Node.js前端项目：适用于React、Vue、Angular等前端框架的自动化构建（如代码 lint、单元测试、打包构建）。
• Node.js后端服务：支持Express、NestJS等后端项目的单元测试、集成测试及服务部署前验证。
• 全栈项目CI/CD：可作为全栈项目（Node.js后端+前端）在CircleCI中的统一执行环境，简化多模块构建流程。

使用方法与配置说明

1. 镜像获取

通过Dockerfile构建或直接拉取已构建的镜像（需替换[镜像仓库地址]和[标签]为实际值）：

bash
docker pull [镜像仓库地址]/circleci-node-image:[标签]

2. 本地测试

如需本地验证镜像环境，可通过以下命令启动容器并进入交互模式：

bash
docker run -it --rm [镜像仓库地址]/circleci-node-image:[标签] /bin/bash

进入容器后，可验证Node.js环境：

bash
node -v  # 查看Node.js版本
npm -v   # 查看npm版本

3. 在CircleCI中集成

在项目的.circleci/config.yml配置文件中，指定该镜像作为执行环境。以下为基础配置示例：

yaml
version: 2.1
jobs:
  build-and-test:
    docker:
      - image: [镜像仓库地址]/circleci-node-image:[标签]  # 使用自定义镜像
    steps:
      - checkout  # 拉取代码
      - run: npm install  # 安装项目依赖
      - run: npm run lint  # 代码检查
      - run: npm run test  # 执行单元测试
      - run: npm run build  # 构建项目（如适用）

workflows:
  version: 2
  ci-pipeline:
    jobs:
      - build-and-test  # 触发构建测试流程

4. 自定义配置

通过Dockerfile调整

如需修改镜像默认配置（如升级Node.js版本、添加额外依赖），可基于原Dockerfile扩展：

dockerfile
# 基于官方Node.js slim镜像构建（示例）
FROM node:18-slim

# 安装额外依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 配置环境变量（可选）
ENV NODE_ENV=production

在CircleCI配置中传递环境变量

通过.circleci/config.yml的environment字段为镜像传递自定义环境变量：

yaml
jobs:
  build-and-test:
    docker:
      - image: [镜像仓库地址]/circleci-node-image:[标签]
    environment:
      - NODE_OPTIONS: "--max-old-space-size=4096"  # 调整Node.js内存限制
      - NPM_REGISTRY: "https://registry.npm.taobao.org"  # 配置npm镜像源
    steps:
      # ... 省略步骤 ...

5. CircleCI配置示例

以下为完整的.circleci/config.yml示例，实现Node.js项目的自动化测试与构建：

yaml
version: 2.1
jobs:
  build-test-deploy:
    docker:
      - image: [镜像仓库地址]/circleci-node-image:18  # 使用Node.js 18版本镜像
    steps:
      - checkout
      - restore_cache:  # 缓存npm依赖，加速构建
          keys:
            - npm-deps-{{ checksum "package-lock.json" }}
      - run: npm ci  # 安装依赖（较npm install更严格，确保依赖版本一致）
      - save_cache:
          paths:
            - node_modules
          key: npm-deps-{{ checksum "package-lock.json" }}
      - run: npm run lint  # 代码规范检查
      - run: npm test  # 执行单元测试
      - run: npm run build  # 构建项目输出
      - store_artifacts:  # 存储构建产物（如dist目录）
          path: dist
      # 部署步骤（根据实际需求添加，如部署至S3、服务器等）

workflows:
  version: 2
  main:
    jobs:
      - build-test-deploy:
          filters:
            branches:
              only: main  # 仅在main分支触发构建

注意事项

• 镜像标签应与项目使用的Node.js版本匹配（如16、18对应Node.js 16.x、18.x版本），避免版本兼容性问题。
• 敏感配置（如API密钥、部署凭证）建议通过CircleCI平台的"环境变量"功能注入，而非硬编码到镜像中。
• 如需扩展镜像功能（如添加数据库客户端、构建工具），建议通过Dockerfile二次构建，避免直接修改基础镜像。