多模块项目中 COPY 的核心是按需分层、避免冗余、精准隔离；应分步 COPY 各模块依赖文件与源码，结合 .dockerignore 过滤无关内容，采用多阶段构建分离构建期与运行期 COPY。
在多模块项目中使用 COPY 指令，关键不是“复制什么”，而是“按需分层、避免冗余、精准隔离”。盲目 COPY 整个源码目录，会导致镜像臃肿、缓存失效频繁、构建变慢，甚至暴露敏感文件。
按模块粒度分步 COPY
多模块项目（如 Maven 的 parent + module-a + module-b，或 Gradle 的 root + subprojects）通常有各自独立的构建产物。不要在根目录下 COPY . /app，而应：
- 先
COPY各模块的pom.xml或build.gradle到对应路径，执行依赖下载（利用 Docker 构建缓存） - 再
COPY对应模块的源码，仅限该模块所需部分（例如只 COPYmodule-a/src，不带module-b） - 最后
RUN ./gradlew :module-a:build生成 jar，再COPY出来的 jar 到最终镜像层
用 .dockerignore 精确过滤无关内容
.dockerignore 是 COPY 的“守门人”。多模块项目中常见陷阱是忽略 */target、*/build、**/node_modules，或误把 settings.gradle、mvnw 当作可忽略项（它们实际参与构建）。建议明确列出：
.git .gitignore README.md **/target/ **/build/ **/node_modules/ **/*.log **/out/
注意：通配符 **/ 能覆盖嵌套子模块路径，比单星号更可靠。
避免跨模块隐式依赖导致 COPY 失效
当 module-b 依赖 module-a 的本地 jar，但构建时未提前 install 到本地仓库，仅 COPY module-b 源码会失败。此时不能靠 COPY 补救，而应：
- 在构建阶段统一执行
./gradlew build（全量构建），再从各模块build/libs/中 COPY 成品 - 或采用多阶段构建：第一阶段构建全部模块并 install 到本地 Maven 仓库；第二阶段仅 COPY 第一阶段中已构建好的 jar 和运行时依赖
- 不推荐在 Dockerfile 中用
COPY手动搬运~/.m2—— 路径不稳定、权限易错、违反分层原则
区分构建期 COPY 与运行期 COPY
多模块项目常混用两类 COPY：
-
构建期 COPY：用于编译，如
COPY pom.xml .、COPY src/ ./src/，应放在builder阶段（多阶段构建中） -
运行期 COPY：用于最终镜像，如
COPY --from=builder /app/module-a/build/libs/*.jar app.jar，只含最小必要文件
运行镜像里不应存在任何 src、pom.xml、gradle/ 目录 —— 它们既不参与运行，又增大攻击面。
多模块项目中的 COPY 不是复制操作，而是构建策略的具象表达。控制好范围、时机和目标层级，才能让镜像轻、快、稳。
