关键在于让COPY指令复用缓存层：按变更频率分层，先拷贝稳定的依赖文件（如package.json），再RUN安装，最后拷贝易变源码；配合.dockerignore排除无关文件、多阶段构建隔离影响、BuildKit提升效率，确保小改动不触发整链重跑。

关键在于让 COPY 指令尽可能复用缓存层，避免因小文件变动导致整条构建链重跑。核心逻辑是：越靠前的 COPY 越稳定，越靠后的 COPY 越容易变；一旦某层缓存失效，它之后的所有层（包括 RUN、CMD 等）全部重新执行。

COPY顺序按变更频率分层

把长期不变的配置类文件放在前面拷贝，频繁修改的源码放在最后。这样即使改了一行代码，也不会触发依赖安装步骤重跑。

• 先 COPY package.json 和 package-lock.json（Node.js）或 requirements.txt（Python）
• 紧接着 RUN 安装依赖（此时能命中缓存）
• 最后 COPY src/ 或 . （应用代码，日常开发中高频变动）

避免一次性 COPY 整个目录

用 COPY . /app 这种写法看似简洁，实则风险最高——只要项目里任意一个文件改动（比如 .gitignore、README.md、日志文件），就会让这一层缓存完全失效。

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

• 显式列出需复制的文件或子目录，如 COPY package*.json ./
• 用 .dockerignore 排除无关文件（node_modules、.git、*.log 等），减少上下文体积和哈希计算干扰
• 不依赖时间戳或路径通配“侥幸”命中，Docker 只认内容哈希

利用多阶段构建隔离 COPY 影响范围

编译型语言（如 Go、Rust）适合用多阶段构建，把构建环境和运行环境彻底分开。这样即使构建阶段的 COPY 频繁变化，也不会污染最终镜像层。

• 构建阶段 COPY 源码 + 编译，只保留二进制文件
• 运行阶段 FROM 更小的基础镜像，仅 COPY 上一阶段生成的可执行文件
• 两个阶段各自缓存独立，互不影响

验证缓存是否真正生效

别只看 “Using cache” 提示，要确认它出现在你期望的位置。构建时加 --progress=plain 参数，观察每一步是否跳过实际执行。

• 如果某次修改了 package.json 后，npm install 步骤没重跑，说明 COPY package.json 层缓存命中
• 如果只是改了 src/main.go 却触发了整个构建重来，大概率是 COPY 位置太靠前或 .dockerignore 没配好
• 本地测试时可删掉镜像缓存 docker builder prune -a，再对比有无缓存的构建耗时差异