RUN mount（--mount=type=cache）不能挂载宿主机目录，而是为构建阶段提供跨构建、可复用的缓存目录，专用于加速 node_modules 等依赖安装；它不参与层哈希计算，避免 package.json 变更导致的缓存失效，显著提升 CI 构建速度。
在 Docker 构建前端项目时，RUN mount（即 BuildKit 的 --mount=type=cache）能显著加速依赖安装和构建过程，但它**不能直接用于 mount 一个已挂载的宿主机目录或运行时文件系统**，也不能替代传统 volume 挂载。它的核心作用是为构建阶段提供**跨构建、可复用、自动管理的缓存目录**，尤其适合 node_modules、yarn cache、pnpm store 等易变但高度重复的中间产物。
为什么 RUN mount 比 COPY node_modules 更高效？
Docker 层缓存（layer cache）在 COPY package*.json . + RUN npm install 链路中极易失效：只要 package.json 或 package-lock.json 有任意一行变动（如更新一个 minor 版本），后续所有层都会重建，包括耗时的依赖安装。而 --mount=type=cache 将依赖安装结果存放在独立缓存路径中，不参与镜像层哈希计算——即使源码变更，只要依赖未变，缓存仍命中，npm install 可秒级完成。
正确配置 npm/yarn/pnpm 缓存 mount
启用 BuildKit 后，在 RUN 指令中显式声明缓存挂载点，并确保包管理器实际使用该路径：
-
npm：需配合
--cache参数指向缓存目录，例如：RUN --mount=type=cache,id=npm-cache,sharing=locked,target=/root/.npm npm ci --cache /root/.npm -
yarn v1：用
--cache-folder：RUN --mount=type=cache,id=yarn-cache,sharing=locked,target=/usr/local/share/.cache/yarn yarn install --frozen-lockfile --cache-folder /usr/local/share/.cache/yarn -
pnpm（推荐）：默认 store 路径可被 mount，且支持硬链接，节省空间和时间：
RUN --mount=type=cache,id=pnpm-store,sharing=locked,target=/pnpm-store --mount=type=cache,id=pnpm-global,sharing=locked,target=/usr/pnpm-global pnpm install --frozen-lockfile
并提前在Dockerfile中设置：ENV PNPM_HOME=/usr/pnpm-globalENV PNPM_STORE_PATH=/pnpm-store
避免常见陷阱
--mount=type=cache 不是万能的，误用反而拖慢构建：
立即学习“前端免费学习笔记（深入）”；
-
不要对整个
node_modules目录做 cache mount：Docker 不允许在构建中直接挂载到node_modules（会与COPY冲突），且node_modules是输出产物，应由包管理器生成并保留在镜像层中；缓存只需管「下载/解压/构建依赖」的过程，而非最终目录本身。 -
注意
sharing模式：多并发构建时，sharing=locked（默认）允许多个构建共享读写缓存（带锁），sharing=private则完全隔离。前端 CI 场景建议保持locked。 -
确保基础镜像支持非 root 用户缓存：若切换到
user node，需将 cache target 设为该用户可写路径（如/home/node/.pnpm-store），并用--chown=node:node或提前chown。
完整最小可行示例（pnpm + React）
（需启用 BuildKit：docker build --progress=plain --build-arg NODE_ENV=production .）
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,id=pnpm-store,target=/pnpm-store \
--mount=type=cache,id=pnpm-global,target=/usr/pnpm-global \
corepack enable && \
pnpm setup && \
export PNPM_HOME="/usr/pnpm-global" && \
export PNPM_STORE_PATH="/pnpm-store" && \
pnpm install --frozen-lockfile
COPY . .
RUN --mount=type=cache,id=pnpm-store,target=/pnpm-store \
--mount=type=cache,id=pnpm-global,target=/usr/pnpm-global \
pnpm run build
FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html
合理使用 --mount=type=cache 后，CI 中依赖安装阶段从 2–5 分钟普遍降至 3–10 秒，构建稳定性与速度同步提升。关键不在“挂载”，而在让缓存真正被包管理器识别并复用。
