锁定依赖版本是构建缓存稳定性的核心前提，需在package.json中使用精确版本号（如"lodash": "4.17.21"）替代^/~符号，并配合npm ci或--frozen-lockfile强制按lockfile安装，同时在docker中分层隔离依赖与代码以提升缓存命中率。

锁定依赖版本是构建缓存稳定性的核心前提。缓存是否命中，不仅取决于指令写法，更取决于该层实际输入内容是否变化；而依赖版本漂移（比如 ^1.2.0 自动升级到 1.3.0）会直接导致 run npm install 或 run pnpm install 这一层的输出不一致，从而让缓存失效——即使 package.json 文件本身没改。

用精确版本号固化依赖声明

在 package.json 中避免使用 ^ 或 ~，改用固定版本：

• 不推荐："lodash": "^4.17.21" → 下次 install 可能拉取 4.18.0，触发缓存重建
• 推荐："lodash": "4.17.21" → 版本严格锁定，安装结果可预期、可复现

配合 lockfile 强制校验与冻结

仅写死 version 不够，还需确保包管理器真正按 lockfile 执行：

• pnpm install --frozen-lockfile：拒绝任何 lockfile 修改，若本地 pnpm-lock.yaml 与当前 package.json 不匹配，构建直接失败，而非静默更新
• npm ci（非 npm install）：只读取 package-lock.json 安装，跳过解析 package.json 的语义，杜绝版本推导
• yarn install --frozen-lockfile：同理，保障 lockfile 是唯一权威来源

在 Docker 构建中分层隔离依赖与代码

Docker 缓存对文件内容敏感，需把“稳定”和“易变”的操作拆到不同层：

• 先 COPY package*.json . → 仅当依赖描述变更时，才触发重装
• 再 RUN pnpm install --frozen-lockfile → 此层缓存高度稳定
• 最后 COPY . . → 源码修改不影响前两层缓存

这样，90% 的日常代码提交都不会导致依赖重装，大幅缩短 CI 构建时间。

补充：避免隐式版本变动干扰

有些场景看似没改依赖，实则悄悄破坏缓存：

• 基础镜像用 node:latest → 底层 Node.js 版本升级，FROM 层哈希变化，全链缓存清空
• CI 环境未清理 node_modules 或 pnpm store → 旧包残留可能影响新构建一致性
• 构建时传入 --build-arg NODE_ENV=development 并用于条件安装 → 参数值一变，RUN 层即失效

建议统一使用 node:18.19.1 这类带完整补丁号的标签，并在 Jenkins 或 GitHub Actions 中显式执行 pnpm store prune && rm -rf node_modules。