企业官网建设流程全解析

Jib 与 Skaffold 集成配置指南：控制文件监视与同步范围（Gradle / Maven）

【免费下载链接】jib🏗 Build container images for your Java applications.项目地址: https://gitcode.com/gh_mirrors/ji/jib

本指南基于 Jib 仓库中的设计提案 proposals/archives/skaffold_config.md 及两个插件中对应的落地实现，系统讲解如何通过skaffold配置块定制 Jib 与 Skaffold 协作时的文件监视（watch）与文件同步（sync）行为。读完本文，你将掌握 Gradle 与 Maven 两种构建体系下buildIncludes/includes/excludes及sync.excludes的完整语义、配置写法与底层输出协议，能够精确控制哪些文件触发 Skaffold 重建、哪些文件被排除在监视与同步之外。

背景：为什么需要控制 Skaffold 监视的文件

Skaffold 与 Jib 协作时，Skaffold 会调用 Jib 插件暴露的专用任务（task / goal）来获取"应该监视哪些文件"的清单，并据此触发镜像重建。默认情况下，Jib 基于自身对项目结构的理解来推断监视范围（构建脚本、源码目录、资源目录、额外目录等）。

但实际项目往往存在 Jib 不了解的中间构建过程：例如在 Jib 处理之前，项目可能先经过代码生成、前端打包、协议编译等步骤，产生 Jib 无从得知的输入文件。提案的动机正是允许用户显式配置这些任务，让监视清单如实反映项目的真实构建流程，从而更高效地使用 Skaffold 的自动重建能力。

提案同时明确了一个边界：最终的 Jib 输出不会偏离 Skaffold 的预期格式，配置只是让用户对"发送给 Skaffold 的内容"拥有更精细的控制权，Skaffold 本身无需任何改动（提案中 "Changes to Skaffold: None"）。

理解 Jib 与 Skaffold 之间的文件清单协议

要理解各项配置的含义，先要掌握 Jib 向 Skaffold 输出的 JSON 结构。核心类 SkaffoldFilesOutput.java 定义了三个列表字段：

{ "build": ["buildFile1", "buildFile2"], "inputs": ["src/main/java/", "src/main/resources/"], "ignore": ["pathToIgnore"] }

三者语义如下：

任务执行时，会先输出空行，再打印BEGIN JIB JSON标记与 JSON 内容（见 FilesTaskV2.java 与 FilesMojoV2.java），Skaffold 通过该标记解析清单。值得注意的一点（源码注释中已明确）：对于ignore不做特殊预处理，inputs与ignore允许以完全匹配的方式重叠。

Gradle 侧配置：jib { skaffold { ... } }

完整配置示例

提案给出的 Gradle 配置形态如下（位于build.gradle）：

jib { ... skaffold { watch { buildIncludes = 'script.gradle' includes = project.files('my/custom/inputs') excludes = ['some/file/i/dont/want/watched'] } sync { exclude = 'a/file' } } }

参数的实际实现语义

在 Gradle 插件中，skaffold配置块由 SkaffoldParameters.java 承载，内部包含watch与sync两个嵌套对象：

• watch（SkaffoldWatchParameters.java）：
  • buildIncludes：追加到build列表的文件（如额外的构建脚本）；
  • includes：追加到inputs列表的文件；
  • excludes：追加到ignore列表的文件；
  • 三者均通过project.files(...)解析，因此接受任何 Gradle 文件集合表达式——单个File、List<File>、List<String>、project.files(...)均可，解析后统一转为绝对路径存入Set<Path>。
• sync（SkaffoldSyncParameters.java）：仅含excludes，用于排除参与 Skaffold 文件同步（sync）的路径，同样经project.files(...)解析为绝对路径集合。

Gradle 默认监视的文件集合

配置是在 Jib 默认推断结果之上做增删，理解默认集合才能正确使用排除项。FilesTaskV2.java 的listFiles()展示了完整的默认收集逻辑：

1. 若非根项目，则加入根项目的build.gradle、settings.gradle（含gradle.properties）；
2. 当前项目的build.gradle、settings.gradle、gradle.properties，以及mainsourceSet 的全部源码目录；
3. jib.extraDirectories中配置且真实存在的额外目录；
4. 传递闭包内所有项目依赖（project dependency）的项目文件；
5. 非项目依赖的SNAPSHOTjar（通过jib.configurationName指定的运行时配置收集，避免重复输出）；
6. 最后叠加用户配置的watch.buildIncludes/watch.includes/watch.excludes。

运行命令（在 Gradle 项目根目录下）：

./gradlew _jibSkaffoldFilesV2 -q # 多模块项目指定子模块： ./gradlew :<subproject>:_jibSkaffoldFilesV2 -q

Maven 侧配置：<skaffold>配置节

完整配置示例

提案给出的 Maven 配置形态如下（位于pom.xml的 jib 插件<configuration>内）：

<configuration> <skaffold> <watch> <buildIncludes> <buildInclude>some/pomfile.xml</buildInclude> </buildIncludes> <includes> <include>some/file</include> <include>another/file</include> </includes> <excludes> <exclude>not/me</exclude> <exclude>/absolute/path/to/not/me</exclude> </excludes> </watch> <sync> <excludes> <exclude>some/file</exclude> </excludes> </sync> </skaffold> </configuration>

参数的实际实现语义

Maven 侧由 SkaffoldConfiguration.java 定义参数结构，与 Gradle 侧一一对应：

• Watch：buildIncludes（List<File>）、includes（List<File>）、excludes（List<File>），默认均为空列表；
• Sync：excludes（List<File>），默认空列表。

<watch>元素本身在配置类中标注为"unused, but left here to define how to parse it"（保留以定义解析方式），实际由 FilesMojoV2.java 的collectWatchParameters()手动从插件配置的 Xpp3Dom 树中读取并填入Watch对象。路径解析规则为：绝对路径直接使用，相对路径基于项目basedir解析为绝对路径（见resolveFiles()）。

Maven 默认监视的文件集合

FilesMojoV2.java 的execute()会遍历 reactor 中所有项目并收集：

1. 每个模块的pom.xml（packaging=pom的聚合模块收集后直接跳过）；
2. Maven 解析出的源码目录（绝对路径）与资源目录；
3. Kotlin 源码目录——若使用kotlin-maven-plugin，会从其<executions>配置中提取<sourceDirs>，并始终追加约定的src/main/kotlin；
4. 显式配置了 jib 插件的项目才纳入extraDirectories目录；
5. 通过ProjectDependenciesResolver解析 compile/runtime 依赖，筛选出非本项目模块的SNAPSHOT依赖 jar；
6. 叠加用户配置的watch.buildIncludes/watch.includes/watch.excludes。

运行命令（在 Maven 项目根目录下）：

./mvnw jib:_skaffold-files-v2 -q # 多模块项目激活单个模块及其依赖模块： ./mvnw jib:_skaffold-files-v2 -pl module -am -q

该 goal 标注为aggregator = true，需requiresDependencyCollection = ResolutionScope.COMPILE_PLUS_RUNTIME，仅服务于 Skaffold 内部使用。

sync 排除的落地：同步映射生成

与"文件监视"不同，"文件同步"（sync）解决的是哪些本地文件可以热同步进容器而不触发完整重建的问题。Jib 通过_jibSkaffoldSyncMap（Gradle）与jib:_skaffold-sync-map（Maven）输出本地文件到容器路径的映射。

SyncMapTask.java 展示了关键约束与处理流程：

• 输出格式为BEGIN JIB JSON: SYNCMAP/1+ JSON；
• 当前仅支持jar类型的项目，war 项目会直接抛错；
• 仅支持exploded（解包）容器化模式，非 exploded 模式会抛出明确错误；
• 最终调用PluginConfigurationProcessor.getSkaffoldSyncMap(...)，并将jib.skaffold.sync.excludes传入，由插件公共层在生成映射时剔除这些路径。

因此，sync.excludes的典型使用场景是：某些文件被 Skaffold 监视（作为inputs会触发重建），但你不希望它们走文件同步通道（例如体积大、或同步后需要完整重建才生效的文件）。

从提案到实现：需要注意的差异

该提案存放于 proposals/archives（已归档），其核心设计——watch.buildIncludes / includes / excludes与sync排除——已按原样落地到两个插件。对照源码可见两处细节差异，使用时以实际实现为准：

1. Gradle 的sync.exclude在实现中为sync.excludes（集合），且经project.files(...)解析；提案示例中的单字符串写法对应源码中可接受集合表达式的 setter。
2. Maven 的sync配置在实现中为<excludes>列表（List<File>），提案示例中的单数<exclude>节点需写成复数列表形态。

另外，若使用较新的 Gradle 版本，FilesTaskV2.java 中settings.gradle的定位通过反射兼容 Gradle 6 与 Gradle 9（getSettingsFile()在 Gradle 9 中被移除），失败时回退到默认的settings.gradle路径——这意味着插件的文件收集逻辑随 Gradle 版本演进而持续维护，配置方式保持稳定。

小结

这套配置让 Jib 在保持与 Skaffold 协议兼容（BEGIN JIB JSON三字段输出、SYNCMAP/1同步映射）的前提下，把"监视什么、同步什么"的决定权交还给开发者，覆盖了代码生成、前端产物等 Jib 无法自行推断的中间构建输入。相关实现可继续深入阅读 FilesTaskV2.java、FilesMojoV2.java、SkaffoldFilesOutput.java 及其配套测试 SkaffoldFilesOutputTest.java。

【免费下载链接】jib🏗 Build container images for your Java applications.项目地址: https://gitcode.com/gh_mirrors/ji/jib