Maven Central发布完整指南：从本地测试到生产部署的最佳实践

发布成功之前，先证明产物可以被使用

将 Kotlin、Android 或 KMP 的共享代码发布为库，可以减少项目间的复制。真正需要建立的流程，是让源代码、版本号、发布产物和消费者验证对应起来。

本文梳理从本地测试到 Maven Central 的发布路径。它假定项目已经配置发布插件、命名空间、签名和凭据；具体插件配置及任务名称随项目而变化，应以项目自身配置与官方文档为准。

修订说明：保留原文章的工作流思路，补充 Central Portal 与快照发布的区别，并修正依赖验证示例。以下示例需要替换为自己的模块和坐标。

先区分三种仓库

位置	用途	注意事项
本地 Maven 仓库	在当前机器验证产物与消费关系	`mavenLocal()` 可能掩盖远程仓库中的缺失或旧产物
快照仓库	持续集成与开发版本测试	`-SNAPSHOT` 采用独立发布路径，不等同于 Central 正式版本
Maven Central	分发正式或预发布坐标	发布后的坐标不可覆盖；修复问题需要发布新版本

Central Portal 支持快照，但发布路径和最终进入 Maven Central 的版本不同。参见官方快照说明与不可变性说明。

一条可以复核的发布链路

1. 查看任务并执行适用的检查

./gradlew tasks --all
./gradlew build
# KMP 项目在具备目标平台环境的机器上执行相应测试
./gradlew allTests

allTests 是否存在取决于项目配置，iOS 等目标还受宿主环境约束。CI 应明确覆盖哪些目标；不要把一台机器上的构建成功等同于所有平台都验证过。

2. 确定版本与发布清单

按语义化版本规范判断兼容性变化，记录版本对应的 Git 提交。检查坐标、POM、源码包、签名及平台产物；KMP 库还要确认消费者需要的平台变体确实在发布清单中。

版本并不只是一段字符串：一旦消费者依赖了某个坐标，就应当能够追溯到生成它的代码和构建环境。

3. 发布到本地仓库并消费

./gradlew publishToMavenLocal

在独立的消费者项目中进行验证，并限制本地仓库影响的坐标范围：

repositories {
    mavenLocal {
        content { includeGroup("com.yourgroup") }
    }
    mavenCentral()
}

dependencies {
    implementation("com.yourgroup:your-library:1.0.0")
}

实际编译消费者并运行关键用例，检查公共 API、资源、传递依赖和平台差异，而不只是确认“仓库里有一个文件”。

4. 上传与检查部署状态

CI 从固定提交生成产物，使用环境或密钥存储注入凭据，不将发布令牌写入仓库。对于希望保留人工检查窗口的发布，可采用 Portal 的手动发布流程：上传后先检查校验结果，再执行发布。

Portal 区分校验、发布中和已发布等状态，处理方式以发布 API 文档为准。不要仅凭上传请求成功判断发布完成，也不要在状态不明时更换产物重复上传相同版本。

5. 从远程仓库做最后一次验证

临时移除消费者项目中的 mavenLocal()，确保仓库配置只指向预期的远程来源，再实际编译与测试。

# 检查 POM 是否已能从远程仓库读取
curl --fail --head \
  "https://repo1.maven.org/maven2/com/yourgroup/your-library/1.0.0/your-library-1.0.0.pom"

# JVM 消费者示例：查看可解析的运行时依赖
./gradlew dependencies --configuration runtimeClasspath
./gradlew build --refresh-dependencies

implementation 主要用于声明依赖，不能把它当作通用的可解析配置。Android 或 KMP 项目应改用对应变体的可解析配置，参考 Gradle 配置职责。POM 可访问也不代表所有平台产物都齐全，仍需实际消费验证。

失败时先分清阶段

本地验证失败：修复实现或发布配置，重新从待发布提交开始验证。
Portal 校验失败：查看部署报告，检查签名、元数据和必要产物。
已发布但无法消费：检查坐标、消费者仓库与平台变体，核对 Portal 状态及缓存。
正式产物已有缺陷：保留已有版本，发布新版本并说明修复或迁移方式。

不承诺固定同步时长。以部署状态、仓库可访问性和实际消费者结果共同判断完成。

发布记录应该留下什么

Release 至少包含版本号、对应提交、支持的平台、变更说明、已执行的验证，以及可能需要的迁移步骤。覆盖率可以帮助定位未验证的行为，但不应以一个统一比例代替对关键路径和兼容性的判断。

这套流程的目标，是让下一次发布可重复，让问题能够追溯，也让使用库的人知道这个版本经过了什么验证。