OkHttp 版本发布流程全指南：从版本号变更、打 Tag 到 Maven Central 自动发布

OkHttp 版本发布流程全指南从版本号变更、打 Tag 到 Maven Central 自动发布【免费下载链接】okhttpA meticulous HTTP client for the JVM, Android, and GraalVM.项目地址: https://gitcode.com/gh_mirrors/okh/okhttp本文以 OkHttp 仓库的 docs/releasing.md 为骨架完整讲解该多模块项目的官方发版流程如何更新 CHANGELOG、如何通过一组sed命令批量替换版本号、如何打 Tag 并切回 SNAPSHOT 开发版本以及如何借助 GitHub Actions 把制品自动构建并发布到 Maven Central。读完本文你将能够独立完成一次 OkHttp或同类 Gradle 多模块项目的版本发布并理解版本号在仓库中的权威位置与 CI 发布的底层机制。一、发布流程总览OkHttp 的官方发布流程高度脚本化全部手动操作仅四步更新CHANGELOG.md记录本次发布的所有变更通过环境变量设置本次发布版本号与下一个开发版本号用sed批量替换仓库中的版本号、提交并打 annotated Tag随后把版本号切回-SNAPSHOT开发版本推送 Tag 触发 GitHub Actions由 CI 自动完成构建、签名与发布到 Maven Central。整个过程的关键思想是本地只负责改版本号 打 Tag制品发布完全交给 CI避免因本机环境差异导致发布产物不一致。二、第 1 步更新 CHANGELOG.md发布前维护者需要先更新仓库根目录的 CHANGELOG.md。该文件采用版本号 发布日期 变更说明的结构组织例如当前仓库中最新记录的Version 5.5.0## Version 5.5.0 _2026-08-16_ This release introduces **opt-in** support for Encrypted Client Hello (ECH)...每个版本小节以## Version X.Y.Z开头紧接着是以下划线包裹的发布日期正文按主题介绍新特性、行为变化与重要修复例如 5.5.0 重点介绍了 ECH 支持与 DNS API 的重大更新大版本历史则归档在 docs/changelogs 目录如changelog_1x.md、changelog_2x.md、changelog_3x.md、changelog_4x.md。在写文章时需要注意CHANGELOG 是用户升级时判断影响面的第一手资料因此发布前必须把本次版本的所有用户可见变更补全不能跳过此步骤直接发版。此外docs/upgrading_to_okhttp_4.md 这类迁移文档也应在涉及破坏性变更时同步更新。三、第 2 步设置版本号环境变量发布脚本使用两个环境变量驱动整个流程export RELEASE_VERSIONX.Y.Z export NEXT_VERSIONX.Y.Z-SNAPSHOT含义如下环境变量示例用途RELEASE_VERSION5.6.0本次正式发布版本号用于替换 README 与构建脚本中的版本NEXT_VERSION5.6.1-SNAPSHOT下一个开发版本号发布提交后立即写入构建脚本两个变量应放在同一条 shell 会话中执行以便后续sed命令直接引用。实际执行时把X.Y.Z替换为真实版本号如5.6.0NEXT_VERSION通常取5.6.1-SNAPSHOT补丁递增或6.0.0-SNAPSHOT大版本递增。四、第 3 步批量替换版本号、打 Tag、准备下一个版本这是整个发布流程的核心原文档给出了一组可直接复用的命令序列。下面逐段拆解其作用并补充仓库内的实现依据。4.1 版本号的唯一权威位置base-conventions先看第一段命令sed -i \ s/version \.*\/version \$RELEASE_VERSION\/g \ build-logic/src/main/kotlin/okhttp.base-conventions.gradle.kts这条命令把 okhttp.base-conventions.gradle.kts 中所有version ...替换为发布版本。这个文件是所有模块共享的基础构建约定其中第 9–10 行写死了整个仓库的坐标group com.squareup.okhttp3 version 5.6.0-SNAPSHOT也就是说OkHttp 的版本号只有一个权威位置build-logic预编译脚本中的version属性。仓库当前正处在5.6.0-SNAPSHOT开发版本发布时这里会被替换成RELEASE_VERSION发布完成后再替换回NEXT_VERSION。这种单一版本源 全局约定的设计避免了在 20 个子模块的build.gradle.kts中逐一维护版本号。各子模块由 settings.gradle.kts 统一纳入构建例如okhttp、okhttp-bom、okhttp-tls、logging-interceptor、mockwebserver3等它们共享同一个 group 与 version。注意sed -i 是 macOS/BSD sed 的写法空字符串表示无备份后缀。在 Linux/GNU 环境下需去掉直接使用sed -i ...。4.2 更新 README 中的依赖坐标接下来两条命令负责把全仓库所有 README 中的依赖坐标批量升到发布版本sed -i \ s/\com.squareup.okhttp3:\([^\:]*\):[^\]*\/\com.squareup.okhttp3:\1:$RELEASE_VERSION\/g \ find . -name README.md sed -i \ s/\/com.squareup.okhttp3\/\([^\:]*\)\/[^\/]*\//\/com.squareup.okhttp3\/\1\/$RELEASE_VERSION\//g \ find . -name README.md第一条匹配形如com.squareup.okhttp3:okhttp:5.5.0的 Gradle/Maven 坐标写法把版本号替换为$RELEASE_VERSION。例如根目录 README.md 中就有implementation(com.squareup.okhttp3:okhttp:5.5.0)、implementation(platform(com.squareup.okhttp3:okhttp-bom:5.5.0))、testImplementation(com.squareup.okhttp3:mockwebserver3:5.5.0)等字样第二条匹配形如/com.squareup.okhttp3/okhttp/5.5.0/的路径式坐标写法如 Maven Central 徽章链接中的路径同样替换为发布版本两条命令都作用于find . -name README.md找到的全部 README 文件根目录及okhttp/、okhttp-tls/、mockwebserver/、samples/等各模块目录下的 README。这样用户从任何模块 README 复制的依赖坐标都会指向刚发布的新版本避免出现文档写旧版本的常见问题。4.3 提交并打 annotated Tag版本号替换完毕后执行提交与打 Taggit commit -am Prepare for release $RELEASE_VERSION. git tag -a parent-$RELEASE_VERSION -m Version $RELEASE_VERSION git push git push --tags值得注意的细节Tag 名称采用parent-$RELEASE_VERSION的格式如parent-5.6.0而不是简单的5.6.0。-a参数表示创建annotated Tag带附注的标签-m Version $RELEASE_VERSION写入附注信息。annotated Tag 会记录打 Tag 者、时间与附注适合作为发布标记先git push推送提交再git push --tags推送全部标签。推送 Tag 是触发 CI 发布的关键动作见第五节。4.4 切回 SNAPSHOT 开发版本发布提交推送完成后立即把版本号恢复为下一个开发版本sed -i \ s/version \.*\/version \$NEXT_VERSION\/g \ build-logic/src/main/kotlin/okhttp.base-conventions.gradle.kts git commit -am Prepare next development version. git push注意这里只修改了base-conventions中的versionREADME 中的依赖坐标保持为已发布的RELEASE_VERSION文档始终展示稳定版本开发版本号只存在于构建脚本内部。这样主分支回到-SNAPSHOT状态继续开发同时文档面向用户展示的是最新稳定版。五、第 4 步等待 CI 构建并发布到 Maven Central本地操作到此结束剩下的全部由 CI 自动完成。原文档中的 [GitHub Actions][github_actions] 链接对应本仓库的 .github/workflows/publish.yml 工作流name: publish on: push: tags: - **工作流的关键配置如下触发条件任何 Tag 的推送push: tags: **与本地git push --tags相衔接运行环境macos-26并通过actions/setup-java按仓库中的.java-version文件安装 Temurin JDK发布命令./gradlew publish即执行 Gradle 的publish任务把全部模块发布到 Maven Central凭据注入通过环境变量ORG_GRADLE_PROJECT_*注入三个 Secret ——SONATYPE_CENTRAL_USERNAME、SONATYPE_CENTRAL_PASSWORDSonatype Central 账号和GPG_SECRET_KEY制品签名私钥Gradle 通过mavenCentralUsername等 project 属性读取。5.1 发布配置的底层实现CI 之所以只需一条./gradlew publish就能完成签名与上传是因为所有模块都应用了 okhttp.publish-conventions.gradle.kts 中的发布约定使用com.vanniktech.maven.publish插件并调用publishToMavenCentral(automaticRelease true)开启自动发布上传后无需人工到 Sonatype 控制台点击 Release自动完成 staging → releasesignAllPublications()对全部制品进行 GPG 签名对应 CI 中注入的GPG_SECRET_KEYPOM 元数据名称、描述、许可证 Apache 2.0、SCM 地址、开发者 Square, Inc.统一在此配置okhttp主模块按 Kotlin Multiplatform 配置发布含 Android/JVM 多平台产物其余 JVM 模块按KotlinJvm配置同时启用binary-compatibility-validator并对各模块的internal包进行 API 校验忽略设置——发布前会比对api/目录下的 API 基线文件如 okhttp/api/jvm/okhttp.api确保没有意外破坏二进制兼容性。这意味着 CI 不仅要编译通过还要通过 API 兼容性校验才能把okhttp、okhttp-bom、logging-interceptor、okhttp-tls、mockwebserver3等 20 个坐标成功发布到com.squareup.okhttp3组下。整个构建使用 Gradle Wrapper当前版本为 Gradle 9.6.1见 gradle/wrapper/gradle-wrapper.properties保证 CI 与本地构建环境一致。六、发布后的验证与常见问题6.1 验证发布结果发布流程结束后可从三个层面验证Tag 与提交确认远端存在parent-版本号Tag且主分支最新提交为 Prepare next development version.CI 状态观察 .github/workflows/publish.yml 对应的运行结果是否全绿制品可解析按 README.md 中更新后的坐标如com.squareup.okhttp3:okhttp:RELEASE_VERSION拉取依赖确认新版本已可被 Gradle/Maven 解析。6.2 常见问题sed报错sed -i 是 macOS 语法Linux 上应改为sed -i也可改用perl -pi -e保持跨平台一致README 未全部更新find . -name README.md会递归查找所有 README请确认没有遗漏samples/、mockwebserver/等子目录下的文件发布失败多数与凭据相关检查 CI 中SONATYPE_CENTRAL_USERNAME、SONATYPE_CENTRAL_PASSWORD、GPG_SECRET_KEY三个 Secret 是否配置且未过期若 API 校验失败则需要先更新对应模块api/目录下的.api基线文件再发版版本号残留发布后可用grep -r version \ build-logic确认base-conventions已回到-SNAPSHOT避免后续开发误用发布版本号。七、小结OkHttp 的发布流程可以概括为文档先行 → 脚本改版本 → Tag 触发 CI → 自动发布四段式CHANGELOG 面向用户交代变更sed命令保证版本号在单一权威位置与全部 README 中同步annotated Tag 作为发布锚点而真正的构建、签名与 Maven Central 自动发布则由 publish.yml 与 publish-conventions 全权负责。对于希望在自己的多模块 Gradle 项目尤其是 Kotlin Multiplatform 项目上建立类似发布流水线的开发者这套单一版本源 批量替换 Tag 驱动 CI的模式具有很高的参考价值——把重复劳动交给脚本与 CI把可靠性交给自动化的 API 校验与签名发布。【免费下载链接】okhttpA meticulous HTTP client for the JVM, Android, and GraalVM.项目地址: https://gitcode.com/gh_mirrors/okh/okhttp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考