GitLab-CI中如何复用NodeJS环境，避免重复安装依赖？

问题描述 #

构建项目部署的GitLab-CI流程时，希望在Install步骤安装NodeJS后，让后续代码质量检查等步骤复用该环境，避免重复安装相同依赖包。但当前配置运行时，ESLint步骤报错npm: command not found。

用户配置代码 #

stages:
- "Install"
- "Code Quality"

"NPM":
  stage: "Install"
  before_script:
    - curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list
    - apt update -y
    - apt install -y nodejs
    - npm install -g npm
    - npm install -g pnpm
    - npm install -g bun
    - npm --version
  script:
    - npm install
    - npm run prod
  artifacts:
    expire_in: 1 days
    paths:
      - node_modules/
      - public/

"ESLint":
  stage: "Code Quality"
  dependencies:
    - "NPM"
  before_script:
    - npm --version
  script:
    - npm run eslint

报错信息 #

/usr/bin/bash: line 159: npm: command not found

原因分析 #

GitLab-CI的每个Job都是独立运行的隔离环境（默认用Docker executor时，每个Job对应新容器），Install步骤中安装的NodeJS仅存在于该Job的环境内，不会自动传递到后续Job。artifacts只能传递指定路径的文件（如node_modules），无法共享系统级别的软件安装（如NodeJS、npm）。

解决方案 #

方案1：使用预安装NodeJS的官方镜像 #

直接为所有需要NodeJS的Job指定官方Node镜像，无需手动安装NodeJS，同时通过artifacts传递依赖包：

stages:
- "Install"
- "Code Quality"

"NPM":
  stage: "Install"
  image: node:20
  script:
    - npm install
    - npm run prod
  artifacts:
    expire_in: 1 days
    paths:
      - node_modules/
      - public/

"ESLint":
  stage: "Code Quality"
  image: node:20
  dependencies:
    - "NPM"
  script:
    - npm run eslint

方案2：自定义包含NodeJS的基础镜像 #

如果需要额外工具（如pnpm、bun），可以构建自定义Docker镜像预先安装好所需工具，再让所有Job使用该镜像：

1. 创建Dockerfile：

FROM node:20
RUN npm install -g npm pnpm bun

2. 构建并推送镜像到GitLab容器注册表，之后在CI配置中替换为该自定义镜像即可。

方案3：使用Shell Executor并缓存Node安装（不推荐） #

若使用Shell executor（直接在runner主机运行Job），可将NodeJS安装到缓存目录，通过GitLab的cache配置共享：

stages:
- "Install"
- "Code Quality"

variables:
  NODE_DIR: "$CI_PROJECT_DIR/.node"

"NPM":
  stage: "Install"
  cache:
    key: node-cache
    paths:
      - $NODE_DIR/
      - node_modules/
  before_script:
    - mkdir -p $NODE_DIR
    - curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list
    - apt update -y
    - apt install -y nodejs --install-recommends
    - npm install -g npm pnpm bun --prefix $NODE_DIR
  script:
    - export PATH="$NODE_DIR/bin:$PATH"
    - npm install
    - npm run prod
  artifacts:
    expire_in: 1 days
    paths:
      - node_modules/
      - public/

"ESLint":
  stage: "Code Quality"
  cache:
    key: node-cache
    paths:
      - $NODE_DIR/
  dependencies:
    - "NPM"
  before_script:
    - export PATH="$NODE_DIR/bin:$PATH"
  script:
    - npm run eslint

注意：此方案依赖runner主机环境，仅适用于私有专属runner，不推荐共享runner场景。

内容的提问来源于stack exchange，提问作者Ruan Pêpe