Docker 构建前端项目应优化缓存：先单独 COPY package.json 和 lock 文件并运行 npm ci，再用 .dockerignore 排除无关文件，结合多阶段构建分离构建与运行环境，并固定基础镜像精确版本。
大型前端项目构建慢，核心问题往往不是打包本身，而是每次 docker build 都从头下载依赖、重新安装 node_modules、重复执行构建命令。Docker 的层缓存机制能彻底改变这一点——关键在于让稳定的部分（如依赖）先执行并命中缓存，让易变的部分（如源码）后执行、不干扰前面的缓存。
把 package.json 和 lock 文件单独 COPY
这是最有效也最容易被忽略的一点。不要用 COPY . . 一次性复制整个项目，那样只要任意一个文件（比如 README.md 或 .gitignore）改动，整个依赖安装层就会失效。
正确做法是分两步：
-
先只复制依赖声明文件：
COPY package.json package-lock.json ./ -
立即运行安装命令：
RUN npm ci --no-audit --no-fund（或yarn install --frozen-lockfile）
只要 package.json 和 lock 文件没变，这一步就永远走缓存，跳过数分钟的依赖下载与解压过程。
立即学习“前端免费学习笔记（深入）”；
用 .dockerignore 排除干扰项
即使你写了精准的 COPY，如果构建上下文里存在大量无关文件（如 node_modules、.git、dist、logs），Docker 仍会把这些文件哈希进上下文计算，导致缓存误失效。
在项目根目录创建 .dockerignore，明确排除这些内容：
node_modules.git-
dist、build、.next（根据框架调整） -
*.log、.env.local、.DS_Store
这样不仅提升缓存稳定性，还能显著减少构建上下文传输体积。
多阶段构建分离构建与运行环境
前端项目通常需要 Node.js 构建环境（含 webpack/vite/esbuild），但最终只需一个静态文件服务器（如 nginx）。多阶段构建能让你：
- 在 builder 阶段专注缓存依赖和构建产物
- 在 production 阶段只保留最小运行时，完全不带 node_modules 或构建工具
示例结构：
# 构建阶段 FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --no-audit COPY . . RUN npm run build <h1>运行阶段</h1><p>FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/nginx.conf
这样，修改源码只影响 builder 阶段的最后一层；package.json 不变时，npm ci 和 npm run build 都可复用缓存。
固定基础镜像标签，避免隐性缓存失效
别用 node:latest 或 node:18 这类浮动标签。它们背后的基础镜像可能随时更新，一旦更新，FROM 层哈希值就变了，整条缓存链立刻断裂。
改用精确语义化版本：
node:18.19.0-alpinenginx:1.25.4-alpine
配合 CI 环境中定期升级版本号（而非自动拉取 latest），既能保证安全更新，又不会意外破坏缓存。
