GitLab CI中Docker构建NestJS时@nestjs/common报错

这个报错和Docker环境一致性机制无关，完全是Dockerfile编写逻辑错误+npm版本在alpine环境的兼容问题导致的：

• 现有多阶段构建逻辑混乱：第二阶段本应只做生产依赖安装、拷贝编译产物的操作，结果先把全量源码拷进镜像，执行npm install时自动触发package.json里定义的postinstall脚本，直接在运行阶段启动了TS编译，完全浪费了第一阶段builder的构建结果。
• 第二阶段使用npm install而非确定性安装命令，GitLab CI的干净构建环境中没有本地完整node_modules做“遮挡”时，npm 8.5.0在alpine镜像的musl libc环境下会随机出现大量小文件写入丢失的问题，直接导致@nestjs/common包内的类型声明文件缺失，触发TS编译报错。本地构建能成功是因为本地开发目录下存在完整的node_modules，被COPY . ./命令拷进了镜像，npm安装时直接复用了本地完整文件，没有触发丢文件的bug。
• 没有配置.dockerignore，构建上下文会把无关文件、可能存在的残留依赖都打进镜像构建流程，进一步增加安装异常的概率。
• 之前尝试重装@nestjs/common无效，是因为npm install检测到node_modules下已有对应版本包时，不会做全量完整性校验和文件替换，缺失的文件不会被补回。

按以下步骤调整即可解决问题：

• 第一步：在项目根目录创建/更新.dockerignore文件，排除无关目录，避免污染构建层：

node_modules
dist
.git
*.log
.gitlab-ci.yml

• 第二步：重构Dockerfile的多阶段逻辑，分离构建和运行阶段的职责，用确定性安装命令规避npm丢文件问题，修正后的内容如下：

# 构建阶段：安装全量依赖、编译TS产物
FROM node:17-stretch-slim As builder
WORKDIR /app
# 提前声明构建阶段环境，保证dev依赖被正常安装
ENV NODE_ENV=development
# 先拷贝依赖描述文件，最大化利用Docker构建缓存
COPY package*.json ./
RUN npm install -g npm@8.5.0
# 用npm ci做确定性安装，严格按照lock文件拉取完整依赖，不做增量复用
RUN npm ci
# 拷贝全量源码后执行生产构建
COPY . .
RUN npm run build:prod

# 运行阶段：只装生产依赖、拷贝编译产物、启动服务
FROM node:17-alpine
WORKDIR /app
# 提前设置生产环境，避免安装dev依赖
ENV NODE_ENV=production
RUN npm install -g npm@8.5.0
# 只拷贝依赖描述文件，不拷全量源码
COPY package*.json ./
# 安装生产依赖时加--ignore-scripts参数，跳过所有生命周期脚本，避免提前触发编译逻辑，同时规避alpine下npm丢文件的bug
RUN npm ci --omit=dev --ignore-scripts
# 从构建阶段只拷贝最终编译好的产物，不拷源码和构建依赖
COPY --from=builder /app/dist ./dist
EXPOSE 3000
# 用exec格式启动命令，避免额外的shell进程开销
CMD ["npm", "run", "launch:production"]

• 调整后不需要额外重装@nestjs/common，也不需要特殊处理CI缓存，直接在GitLab CI重新执行构建即可。

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