镜像里的 npm 安装
Node 项目在镜像里装依赖推荐用 npm ci：严格按 package-lock.json 安装且不修改锁文件，锁文件缺失或与 package.json 不一致时直接失败。构建环境要的是可复现，这正是它比 npm install 更合适的原因。
基本信息
| 顺序 | 先复制 package.json 与锁文件，再执行安装，最后复制源码 |
|---|---|
| 生产依赖 | npm ci --omit=dev 跳过开发依赖 |
| 清理 | 未使用缓存挂载时，安装后执行 npm cache clean --force |
| 失败条件 | 锁文件缺失或与 package.json 不一致 |
| 基础镜像 | node:20-alpine 自带 node 用户，运行阶段可以直接 USER node |
典型使用场景
- 构建前端产物：构建阶段装全量依赖编译，运行阶段只装生产依赖
- 保证构建可复现：锁文件固定版本，避免不同机器装出不同依赖
- 访问私有源：配合 .npmrc 与 secret 挂载完成内部 registry 认证
- 多阶段构建中把依赖安装单独放一层，改代码不必重装依赖
- 排查线上依赖问题时核对镜像内实际安装的版本是否与锁文件一致
- 排查原生模块编译失败：构建阶段补 python、make、g++ 等工具链
示例
示例
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY dist/ ./dist/
# 用缓存挂载加速时，不要再执行 npm cache clean
RUN --mount=type=cache,target=/root/.npm \
npm ci --omit=dev --prefer-offline安装命令怎么选
| 命令 | 行为 | 适用场景 |
|---|---|---|
| npm ci | 按锁文件精确安装，不修改锁文件 | CI 与镜像构建，推荐 |
| npm install | 可能更新锁文件，按范围解析版本 | 本地开发新增或升级依赖 |
| npm ci --omit=dev | 跳过开发依赖 | 生产运行镜像 |
| npm ci --omit=optional | 跳过可选依赖 | 可选原生依赖存在兼容问题时 |
先复制 package.json 与锁文件、再复制源码，改一行代码不会触发依赖整层重装，构建时间差别相当明显。
混用 npm、yarn、pnpm 会同时留下多份锁文件，构建时用错包管理器等于锁文件形同虚设，一个项目只保留一套。
npm 版本会随基础镜像更新，锁定 node 镜像的次版本能让构建更稳定；跨大版本升级后先本地跑一遍安装再改流水线。