多模块项目中 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 对应模块的源码，仅限该模块所需部分（例如只 COPY module-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 不是复制操作，而是构建策略的具象表达。控制好范围、时机和目标层级，才能让镜像轻、快、稳。