ninoxdatabase/nxdb-nodejs

Node.js CircleCI构建镜像

镜像概述和主要用途

本镜像是专为CircleCI构建流水线优化的Node.js环境镜像，基于官方Node.js镜像构建，集成CI/CD流程所需的核心工具与依赖。主要用于在CircleCI持续集成/持续部署平台中，执行JavaScript/TypeScript项目的构建、测试、代码检查、打包及部署前置任务，确保流水线高效、稳定运行。

核心功能和特性

基础特性

• 官方兼容性：基于Docker官方Node.js镜像构建，保证与Node.js生态系统的兼容性。
• 多版本支持：通过镜像标签提供不同Node.js版本（如16-circleci、18-circleci、20-circleci），适配项目对Node.js版本的需求。

CI/CD优化特性

• 预装核心工具：集成npm、yarn、pnpm等包管理器，以及git、curl、wget、jq等CI常用工具，减少流水线工具安装步骤。
• 缓存机制适配：支持CircleCI缓存策略（如node_modules目录缓存），加速依赖安装环节。
• 轻量级设计：精简镜像体积，减少CircleCI工作节点拉取镜像的时间开销。
• 构建稳定性：内置构建过程错误捕获与日志优化，便于流水线问题排查。

使用场景和适用范围

适用项目类型

• 前端项目：React、Vue、Angular、Next.js等JavaScript/TypeScript前端框架项目。
• 后端服务：Node.js Express、NestJS、Koa等后端服务项目。
• 全栈应用：包含前端与Node.js后端的全栈JavaScript项目。

典型使用场景

• 在CircleCI中执行代码 linting（如ESLint检查）。
• 运行单元测试、集成测试（如Jest、Mocha测试框架）。
• 构建项目产物（如前端打包、后端代码编译）。
• 生成部署 artifacts（如Docker镜像、静态资源包）。

使用方法和配置说明

前置条件

• 已配置CircleCI账户并关联代码仓库。
• 项目根目录下存在.circleci/config.yml配置文件。

CircleCI配置示例

在.circleci/config.yml中指定本镜像作为构建环境，示例如下：

yaml
version: 2.1

jobs:
  build-and-test:
    docker:
      - image: [镜像名称]:18-circleci  # 替换为实际镜像名称，如`myorg/node-circleci:18-circleci`
    steps:
      - checkout  # 拉取代码仓库

      # 缓存依赖（加速下次构建）
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}  # 根据锁文件哈希缓存
            - v1-deps-  # 回退缓存

      # 安装依赖
      - run:
          name: 安装依赖
          command: npm ci  # 或使用 yarn install --frozen-lockfile

      # 缓存依赖（保存本次依赖）
      - save_cache:
          paths:
            - node_modules
            - ~/.npm
          key: v1-deps-{{ checksum "package-lock.json" }}

      # 代码检查
      - run:
          name: 代码Linting
          command: npm run lint

      # 运行测试
      - run:
          name: 单元测试
          command: npm test

      # 构建项目
      - run:
          name: 构建产物
          command: npm run build

      # 保存构建产物（如需后续部署）
      - store_artifacts:
          path: dist/  # 替换为实际构建产物目录

workflows:
  version: 2
  main-pipeline:
    jobs:
      - build-and-test:
          filters:
            branches:
              only: main  # 仅在main分支触发

镜像标签说明

镜像通过标签区分Node.js版本，格式为{node-version}-circleci，例如：

• 16-circleci：基于Node.js 16.x版本构建
• 18-circleci：基于Node.js 18.x版本构建（推荐长期支持版）
• 20-circleci：基于Node.js 20.x版本构建

环境变量配置

可通过CircleCI environment字段或镜像运行时注入环境变量，常用配置如下：

本地测试（可选）

如需在本地模拟CircleCI构建流程，可通过docker run命令运行镜像：

bash
# 拉取镜像
docker pull [镜像名称]:18-circleci

# 挂载项目目录并执行构建命令
docker run --rm -v $(pwd):/app -w /app [镜像名称]:18-circleci sh -c "npm install && npm run build"

注意事项

• 选择与项目匹配的Node.js版本标签，避免版本兼容性问题。
• 结合CircleCI cache和artifacts功能，最大化流水线效率。
• 敏感配置（如API密钥）通过CircleCI项目环境变量注入，避免硬编码到配置文件中。