自定义GitLab CI前端部署镜像执行npm install报错排查

问题背景 #

我希望制作包含默认构建工具的GitLab CI自定义镜像，推送代码至GitLab服务器时拉取该镜像并安装依赖。已基于node:16-alpine3.16制作了包含AWS CLI的镜像，编译及容器运行均正常，但本地使用gitlab-runner exec docker code_review命令执行.gitlab-ci.yml中code_review阶段的npm install时出现报错，想咨询：

1. 操作中的错误点
2. 需求的可行性
3. 正确的实现方式

提供的配置文件 #

自定义镜像Dockerfile #

FROM node:16-alpine3.16

RUN apk --no-cache add zip
RUN apk --no-cache add curl
ARG GLIBC_VERSION=2.35-r0

RUN apk --no-cache add \
        binutils \
        curl \
    && curl -sL https://alpine-pkgs.sgerrand.com/sgerrand.rsa.pub -o /etc/apk/keys/sgerrand.rsa.pub \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-${GLIBC_VERSION}.apk \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-bin-${GLIBC_VERSION}.apk \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-i18n-${GLIBC_VERSION}.apk \
    && apk add --no-cache glibc-${GLIBC_VERSION}.apk glibc-bin-${GLIBC_VERSION}.apk \
        glibc-i18n-${GLIBC_VERSION}.apk \
    && /usr/glibc-compat/bin/localedef -i en_US -f UTF-8 en_US.UTF-8 \
    && ln -sf /usr/glibc-compat/lib/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2 \
    && curl -sL https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip \
    && unzip awscliv2.zip \
    && aws/install \
    && rm -rf awscliv2.zip aws \
        /usr/local/aws-cli/v2/current/dist/aws_completer \
        /usr/local/aws-cli/v2/current/dist/awscli/data/ac.index \
        /usr/local/aws-cli/v2/current/dist/awscli/examples \
        glibc-*.apk \
    && find /usr/local/aws-cli/v2/current/dist/awscli/botocore/data -name examples-1.json -delete \
    && apk --no-cache del binutils curl \
    && rm -rf /var/cache/apk/*

RUN aws --version

项目.gitlab-ci.yml配置 #

image: customImage/Name

stages:
  - code_review

code_review:
  stage: code_review
  script:
    - npm install

错误点排查 #

1. 镜像本地可访问性问题 #

gitlab-runner exec docker默认会尝试从远程镜像仓库拉取镜像，如果你的customImage/Name仅在本地构建未推送，runner会因找不到镜像报错。即使镜像存在本地，runner也可能优先尝试拉取远程版本，导致冲突。

2. 用户权限问题 #

Alpine版node镜像默认使用node用户运行，但GitLab Runner执行时可能以root用户启动容器，导致npm install写入node_modules时权限不匹配；或者镜像未配置工作目录权限，无法正常写入依赖文件。

3. 依赖编译工具缺失 #

你的项目如果包含需要编译的native模块，Alpine镜像默认缺少python3、make、g++等基础编译工具，会导致npm install时编译失败。当前Dockerfile仅安装了zip和curl，未包含这些编译依赖。

4. 网络源问题 #

Alpine镜像默认的npm源在本地环境可能访问缓慢或被限制，导致依赖拉取超时失败。

需求可行性 #

你的需求完全可行：制作包含构建工具和AWS CLI的自定义镜像，能大幅减少CI流程中重复安装依赖的时间，同时保证所有CI任务的环境一致性，是团队优化CI/CD流程的常规方案。

正确实现方式 #

1. 确保本地runner能访问镜像 #

本地测试时，先给构建好的镜像打标签，然后强制runner使用本地镜像：

# 构建并打标签
docker build -t customImage/Name .
# 执行runner命令时禁用拉取远程镜像
gitlab-runner exec docker --pull-policy never code_review

如果是GitLab服务器使用，需将镜像推送到GitLab Container Registry或私有镜像仓库，在.gitlab-ci.yml中填写完整的镜像地址（如registry.gitlab.com/your-project/custom-image:tag），并确保runner有权限拉取。

2. 修复镜像依赖与权限问题 #

修改Dockerfile，补充编译依赖并配置正确的工作目录权限：

FROM node:16-alpine3.16

# 添加native模块编译所需工具（按需保留）
RUN apk --no-cache add zip curl python3 make g++

ARG GLIBC_VERSION=2.35-r0

RUN apk --no-cache add \
        binutils \
        curl \
    && curl -sL https://alpine-pkgs.sgerrand.com/sgerrand.rsa.pub -o /etc/apk/keys/sgerrand.rsa.pub \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-${GLIBC_VERSION}.apk \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-bin-${GLIBC_VERSION}.apk \
    && curl -sLO https://github.com/sgerrand/alpine-pkg-glibc/releases/download/${GLIBC_VERSION}/glibc-i18n-${GLIBC_VERSION}.apk \
    && apk add --no-cache glibc-${GLIBC_VERSION}.apk glibc-bin-${GLIBC_VERSION}.apk \
        glibc-i18n-${GLIBC_VERSION}.apk \
    && /usr/glibc-compat/bin/localedef -i en_US -f UTF-8 en_US.UTF-8 \
    && ln -sf /usr/glibc-compat/lib/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2 \
    && curl -sL https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip \
    && unzip awscliv2.zip \
    && aws/install \
    && rm -rf awscliv2.zip aws \
        /usr/local/aws-cli/v2/current/dist/aws_completer \
        /usr/local/aws-cli/v2/current/dist/awscli/data/ac.index \
        /usr/local/aws-cli/v2/current/dist/awscli/examples \
        glibc-*.apk \
    && find /usr/local/aws-cli/v2/current/dist/awscli/botocore/data -name examples-1.json -delete \
    && apk --no-cache del binutils curl \
    && rm -rf /var/cache/apk/*

# 创建工作目录并设置node用户权限
WORKDIR /app
RUN chown -R node:node /app
USER node

RUN aws --version
RUN npm --version

3. 优化CI配置 #

添加npm源配置（可选），确保依赖拉取顺畅：

image: customImage/Name

stages:
  - code_review

code_review:
  stage: code_review
  before_script:
    # 切换国内源加速依赖安装（可选）
    - npm config set registry https://registry.npmmirror.com
  script:
    - npm install

4. 本地验证 #

重新构建镜像后，用runner命令测试：

docker build -t customImage/Name .
gitlab-runner exec docker --pull-policy never code_review

内容的提问来源于stack exchange，提问作者Phoenix404