Marker Artifact 是 Gradle 插件的“身份证”，本身无代码、不参与构建，仅用于声明插件 ID 对应的真实实现坐标；Gradle 7.0+ 强制要求其存在且版本、groupId、artifactId（固定为 gradle-plugin）及 POM 中依赖声明必须与真实插件 jar 严格一致，否则 plugins { id 'xxx' version 'y.z' } 将直接失败。
Marker Artifact 是 Gradle 插件的“身份证”，不是功能组件
Gradle 7.0+ 强制要求插件必须通过 plugin marker artifact 发布，否则 plugins { id 'xxx' } 块会直接失败。它本身不包含任何代码、不参与构建逻辑，唯一作用是告诉 Gradle：“这个插件 ID 对应哪个真实实现坐标”。没有它，Gradle 就不知道该去哪下载真正的插件 jar。
为什么不能直接用 implementation 依赖插件 jar？
因为 plugins { } 块在配置阶段早期就触发解析，此时项目自身的 repositories 和 dependencies 还没加载。Gradle 必须靠独立、可预测的坐标（通常是 gradlePluginPortal() 或你配的私有仓库）提前定位插件。Marker Artifact 就是这个“可预测坐标”的载体：
- 它的
groupId和插件 ID 保持一致（如com.example.myplugin） - 它的
artifactId固定为gradle-plugin（Maven）或plugin（Gradle Module Metadata） - 它的
version必须和真实插件 jar 的版本严格对齐 - POM 文件里通过
<dependency></dependency>明确声明对真正插件 jar 的依赖
常见错误：Marker Artifact 和真实插件 jar 版本不一致
这是本地调试或 CI 发布时最常踩的坑。现象是：Plugin [id: 'com.example.myplugin', version: '1.2.0'] was not found，但明明 jar 已上传。根本原因是：
- Marker Artifact 的 POM 中写的依赖是
com.example.myplugin:myplugin:1.2.0 - 而你实际上传的插件 jar 坐标是
com.example.myplugin:myplugin:1.2.0-SNAPSHOT或1.2.1 - Gradle 按 POM 去拉取，找不到对应版本，直接报错
验证方式：用 curl 直接请求 Marker Artifact 的 POM URL，检查其中 <dependency></dependency> 的 <version></version> 是否匹配你发布的 jar 版本。
发布时如何自动生成正确的 Marker Artifact
别手写 POM。用 Gradle 官方 java-gradle-plugin + maven-publish 插件组合，它会在 publishPlugins 或 publishToMavenLocal 任务中自动为你生成合规的 Marker Artifact：
- 确保插件类继承
Plugin<project></project>并添加@GradlePlugin注解（Kotlin）或gradlePlugin { plugins { ... } }配置块（Groovy/KTS） - 在
publishing { publications { pluginMaven(MavenPublication) { from(components.java) } } }中声明 publication - 执行
./gradlew publishPluginPublicationToMavenRepository，它会同时发布 marker 和真实 jar
手动拼装或跳过 java-gradle-plugin，大概率导致 Marker Artifact 缺失 gradle-plugin classifier 或依赖声明错误——这类问题在 Artifactory 界面里看不出来，但 Gradle 解析时立刻失败。
Marker Artifact 的关键不在“有”，而在“准”：坐标、版本、依赖声明三者必须严丝合缝。它不运行，但决定整个插件能否被找到；不写逻辑，但卡住所有后续构建流程。漏掉它，plugins { } 就是死路一条。
