必须使用com.gradle.plugin-publish插件且Gradle≥7.6，gradlePlugin块须置于插件模块根build.gradle中，id需全局唯一（如io.github.xxx.myplugin），implementationClass须为完整类名并实现Plugin，website与vcsUrl必须是有效https URL，API key须配在用户主目录~/.gradle/gradle.properties中。
必须用 com.gradle.plugin-publish 插件，且 Gradle 版本不能低于 7.6 —— 否则 website、vcsUrl 等必需字段会报错 “unknown property”。
gradlePlugin 块配置必须完整且位置正确
Gradle Plugin Portal 要求插件元信息严格符合规范，gradlePlugin 块不能写在子项目或错误作用域里，必须放在插件模块的根 build.gradle 或 build.gradle.kts 中（即定义 implementationClass 的那个模块）。
-
id必须是全局唯一字符串，推荐用反向域名格式，如io.github.xxx.myplugin -
implementationClass必须是完整类名（含包路径），且该类必须实现org.gradle.api.Plugin<project></project> -
displayName和description不能为空，会被直接显示在插件页面上 -
tags至少填 2–3 个有意义的关键词，比如["android", "build", "performance"] -
website和vcsUrl必须是有效 URL（以https://开头），否则 publish 任务会失败
API key 必须配在 ~/.gradle/gradle.properties
不是插件模块下的 gradle.properties，也不是项目根目录下的，而是用户主目录下的全局 Gradle 配置文件。漏配或配错位置会导致 publishPlugins 任务卡在认证环节，报错类似 Failed to authenticate with plugin portal。
- 文件路径：Linux/macOS 是
~/.gradle/gradle.properties，Windows 是%USERPROFILE%\.gradle\gradle.properties - 必须包含两行：
gradle.publish.key=xxx和gradle.publish.secret=yyy - key 和 secret 来自 https://plugins.gradle.org/user/profile 页面生成，仅显示一次，务必保存
- 该文件权限建议设为
600（macOS/Linux），避免被其他进程读取
publishPlugins 任务不出现？检查插件和 IDE 配置
常见原因是插件未正确声明，或 IDE 没刷新任务列表。Android Studio 默认隐藏非标准 task，尤其在较新版本中。
- 确保插件模块已应用
id 'com.gradle.plugin-publish'（Groovy）或alias(libs.plugins.plugin.publish)（KTS） - 确认
plugins { id 'java-gradle-plugin' }已启用 —— 缺少它会导致gradlePluginDSL 不可用 - 在 Android Studio 中：File → Settings → Build, Execution, Deployment → Build Tools → Gradle → 勾选 “Show all tasks in the Gradle tool window”
- 执行
./gradlew tasks --all | grep publish，确认命令行下能看到publishPlugins - 如果仍无反应，删掉
.gradle缓存并重新 sync
真正容易被忽略的是 vcsUrl 字段：它不仅是展示用，Plugin Portal 会尝试通过它解析仓库语言、检测 README、甚至关联 issue —— 如果填了无效地址（比如私有 GitLab 地址未开放访问），审核可能被人工驳回。发布后别急着关页面，等 10–15 分钟再刷插件详情页，首次发布常有缓存延迟。
