告别手工发布：用JReleaser打造跨平台Java发布流水线

简介这份PDF文档专注于JReleaser工具系统讲解如何为Java项目构建跨平台打包与自动化发布流水线。内容从技术背景与问题痛点切入逐步展开JReleaser的核心功能、常见打包格式JAR、ZIP、DMG、MSI及跨平台打包挑战并给出Maven/Gradle项目集成、发布目标配置GitHub Releases、Maven Central等、持续集成工具联动、错误处理与最佳实践等完整落地路径适合需要统一多平台发布流程的Java后端、桌面应用开发者参考。资源以单个PDF文件呈现压缩包大小4.18MB文内已支持目录章节跳转及阅读器左侧大纲显示便于快速定位知识点。目前已有59人学习下载若正在处理跨平台打包发布效率问题可借助此文档理清配置思路与实践要点减少重复踩坑。 从一次让我濒临崩溃的发布开始说吧。当时项目已经跑完了所有测试mvn clean package产物也出来了接下来要做什么打 tarball、算 SHA-256、写 GitHub Release 草稿、把二进制传到仓库、给 Homebrew 提一个 formula 更新 PR、再跑到 Discord 里喊一嗓子“新版本发布了”。这些事情本身不难但每个版本都手工来一遍绝对能把人磨到怀疑人生。尤其是当你需要同时管 Windows、macOS、Linux 三个平台的安装包时那个酸爽程度已经不亚于在生产环境修数据了。后来我把这整条链路交给了 JReleaser才真正体会到什么叫“发布流水线”。它不是一个打包工具也不是 CI 系统而是把“构建完成之后、用户拿到软件之前”那段灰色地带全部接管过去的自动化框架。这篇文章我不想照着官方文档念一遍而是把我搭建这条跨平台打包发布流水线的完整思路、配置、以及踩过的坑原原本本写出来。适合谁看已经被发布流程烦到不行、或者想从第一天就把发布做成“一键触发”的 Java 项目维护者。1. 为什么项目会需要一个“最后的流水线”先说清楚一个容易混淆的点Maven 和 Gradle 把源码变成 jar、war、可执行 jar这是“构建”但用户真正拿到手的往往是安装包、压缩包、dmg、msi、Homebrew 公式这些东西。从构建产物到用户下载链接之间其实还存在一条没人替你操心的链路。1.1 手工发布时我踩过的重复劳动我在维护一个开源 CLI 工具时每个版本都要经历这样一套流程手动改版本号打 tag推 GitHub。在本地分别跑三遍打包命令或者在 CI 里写三个 job 分别构建。把三个平台的产物下载下来逐个跑shasum -a 256生成校验和。到 GitHub Releases 页面手工创建 release粘贴 changelog上传二进制。如果还发了 Homebrew得手动编辑 formula把新版本的 URL 和 sha256 替换进去再提一个 PR。最后登录 Discord 或 Twitter发一条通知。这些步骤里几乎没有一步需要智力判断但每一步都有手滑的可能URL 写错、校验和忘记更新、tarball 漏了可执行权限位。而且你没法保证三个平台的包用的是同一份代码——万一某个 job 因为缓存问题用了旧版本呢1.2 JReleaser 在整条链路里的位置JReleaser 做的事情是把上述这些“发行动作”定义成一套可复用的流水线。你可以把它理解成一个发布环节的编排器它不负责编译但负责把编译产物“收集”起来按不同平台装配成不同分发格式签名、生成校验和、上传到各种分发渠道再触发通知。这么说可能还有点抽象。换个说法构建系统产出的是“零件”JReleaser 是“总装车间”GitHub Releases、Docker Hub、Homebrew、Scoop、Maven Central 都是“门店”。它解决的根本问题是让“总装”这件事不再依赖人工并且保证每次总装的流程完全一致。基于这种定位我在设计流水线时最核心的原则就是凡是 JReleaser 能声明的环节绝不手写脚本去实现。这样换来的是可重复性和可审计性代价则是我得花时间理解它的配置模型——这正是本文后面要展开的重点。2. 领域模型拆解发布不是一步而是一条多阶段流水线JReleaser 的配置结构初看有些唬人一大堆 XML 或 YAML 节点层级还很深。但别被它吓到它的核心模型其实非常清晰你可以把整条流水线想象成五段接力赛。2.1 五类核心任务的分工这五类核心任务分别是收集与装配、打包镜像、签名、分发、通知。我整理了一个表格方便你对照理解自己项目里哪个环节缺了哪一段阶段配置区域典型任务输出物收集与装配assemble把 jar、脚本、README 组织成标准目录结构解压即用的 tar/zip打包镜像jlink、jpackage生成带 JRE 的精简运行时/原生安装包dmg、msi、pkg、app-image签名与校验signingGPG 签名、生成校验和asc 文件、sha256sum分发distribute上传至 GitHub Releases、Homebrew 等Release 资源、PR通知announce推送发布消息到社区渠道Discord/Slack/Twitter 消息这里有一件很多人忽略的事JReleaser 不是帮你执行jpackage的魔法师它的职责是在正确的时间点用正确的参数把包“装配”成最终形态并送出去。所以哪怕你的项目已经用 GitHub Actions 做了交叉编译依然可以把“如何发布产物”这件事单独交给 JReleaser 来编排。2.2 每个任务的可插拔设计JReleaser 的不同任务都是可独立启停的。我第一次用的时候设置了signing: active: always后来发现本地开发时每次 dry-run 都要等 GPG 走一遍很烦。于是改成了active: RELEASE只在正式发布时启用签名。这种“条件触发”的模型让我可以把本地调试和真正的发布流水线跑在同一套配置文件里。调试时用JRELEASER_PROJECT_VERSION1.0.0-SNAPSHOT jreleaser release -g跑一把本地只会看到装配好的目录和校验和发布时 CI 里设置同样的版本号它就会按部就班地签名、上传、发通知。2.3 幂等性设计给流水线兜底一条可靠的流水线必须有失败重试的底气JReleaser 在这方面做得很务实发布操作大多带幂等语义。比如release -g可以反复执行它不会重复创建同名 Release而是更新已有的。distribute上传文件时如果远端已有相同文件且校验和一致它可以跳过或覆盖取决于你的配置。这一点在真实发布场景里太重要了。我在搭建流水线时遇到过一种情况Docker 镜像已经推上去但 GitHub Release 因为网络原因上传失败。没有幂等设计的话整个流程只能回滚重来有了幂等能力重新跑一遍流水线就好。3. 动手搭一条三平台发布流水线目录、配置与 CI 协作理解了领域模型接下来是硬核实操环节。为了讲得具体我以一个给用户提供命令行工具的 Java 项目为例目标是每次打 tag 后自动产出 Linux 的 tar.gz、macOS 的 dmg、Windows 的 zip并且发布到 GitHub Releases顺带创建 Homebrew formula 的更新 PR。3.1 项目里的 JReleaser 配置骨架我的项目使用的是 JReleaser 的 Maven 插件引入插件后在pom.xml里只需要触发jreleaser:release这么一个 goal。所有发布细节都收敛到一个文件jreleaser.yml。project: name: my-cli-tool version: 2.1.0 description: A handy command-line tool for developers license: Apache-2.0 authors: - DevLuo links: homepage: https://github.com/devluo/my-cli-tool java: groupId: io.devluo artifactId: my-cli-tool version: 17 release: github: owner: devluo name: my-cli-tool tagName: v{{projectVersion}} overwrite: true skipTag: true注意这里的skipTag: true因为我在 GitHub Actions 里已经用softprops/action-gh-release或 git push 方式打过 tag 了JReleaser 没必要再打一次。这只是开始真正的重点在distributions和distribute这两节。3.2 distributions定义不同平台的“发布单元”JReleaser 中一个 distribution 就是一个“用户可下载的东西”。它可以对应 jar、jlink 镜像、jpackage 安装包或者仅仅是原样打包的目录。我通常的做法是在 CI 里先把各平台的最终产物构建出来再用 JReleaser 做组装和分发。distributions: my-cli-tool: type: BINARY artifacts: - path: target/distributions/{{projectName}}-linux-amd64.tar.gz platform: linux-x86_64 - path: target/distributions/{{projectName}}-macos-x86_64.tar.gz platform: osx-x86_64 - path: target/distributions/{{projectName}}-macos-aarch64.tar.gz platform: osx-aarch64 - path: target/distributions/{{projectName}}-windows-x86_64.zip platform: windows-x86_64这里type: BINARY表示我不需要 JReleaser 再加工内容它只需要把 artifact 登记到这个 distribution 名下。平台后缀很重要后续 JReleaser 会利用它来判断哪个文件该进 Homebrew 的 osx 分支、哪个该进 Windows 分支。3.3 签名、校验和与分发渠道配置签名我是只在正式 release 时开的signing: active: RELEASE armored: true mode: MEMORY gpg: keyId: 0xCAFEBABEmode: MEMORY表示 GPG 密钥信息通过环境变量JRELEASER_GPG_PASSPHRASE传入而不是写在 YAML 里。Armored 模式生成的是.asc后缀的 ASCII 签名文件更适合随处存放。分发到 GitHub Releases 的配置则非常简单distribute: github: owner: devluo name: my-cli-tool tagName: v{{projectVersion}}如果还要发布 Homebrew可以再加一节homebrew: owner: devluo name: my-cli-tool formulaName: my-cli-tool commitMessage: Brew formula update for my-cli-tool version {{projectVersion}}它的逻辑是读取我配置的 GitHub Releases 里的 artifact 信息自动生成或更新 formula 文件然后推送到一个独立的 tap 仓库。这里的formulaName一定要和 artifact 命名规则匹配否则生成的 formula 里找不到对应包名。3.4 GitHub Actions 工作流三平台矩阵与 JReleaser 调用我用的 CI 思路是这样的用一个矩阵 job 在三台不同的 runner 上分别构建原生的安装包然后上传 artifact接着一个发布 job 负责把 artifact 下载下来在同一个 runner 上运行 JReleaser。name: release on: push: tags: - v* jobs: build: strategy: matrix: include: - os: ubuntu-latest archive: tar.gz - os: macos-latest archive: tar.gz - os: windows-latest archive: zip runs-on: ${{ matrix.os }} steps: - uses: actions/checkoutv4 - uses: actions/setup-javav4 with: distribution: temurin java-version: 17 - run: mvn clean package -DskipTests - uses: actions/upload-artifactv4 with: name: distribution-${{ matrix.os }} path: target/distributions/* publish: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-javav4 with: distribution: temurin java-version: 17 - uses: actions/download-artifactv4 with: path: artifacts - run: | mkdir -p target/distributions find artifacts -name *.tar.gz -o -name *.zip | xargs -I{} cp {} target/distributions/ - run: mvn jreleaser:release -DskipTests env: JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} JRELEASER_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} JRELEASER_HOMEBREW_GITHUB_TOKEN: ${{ secrets.PAT_BREW }}别小看find artifacts ... | xargs -I{} cp {} target/distributions/这一步它其实是在帮 JReleaser 把所有平台的产物汇总到它期望读取的目录里。如果不做这个合并JReleaser 会因为找不到某个平台 artifact 而直接失败。4. 从“能跑”到“稳定”我在这条流水线上真实踩过的坑配置跑通只是第一步能稳定跑上一百个版本才是真本事。下面这些坑都是我实际遇到过的有些甚至困扰了我好几天这里按影响程度从高到低列出来。4.1 jlink 瘦身过度把模块裁没了最开始我图省事在 jlink 里手动指定--strip-native-commands --no-header-files --no-man-pages想着能小一点是一点。结果某个只在运行时才反射加载java.net.http的模块在瘦身后的 JRE 里根本不存在程序一启动就抛ClassNotFoundException。后来我学乖了先用jdeps --print-module-deps分析出真实依赖再手动补充可能用到反射的模块。如果实在不确定宁可多带一个模块也不裁。省那几百 KB 的体积不值得换一个线上故障。JReleaser 允许你在jlink配置里显式传入addModules这时要格外谨慎。4.2 GPG 签名在 CI 里的密码传递JReleaser 文档推荐用mode: FILE把私钥和口令写到单独目录。但我更推荐用mode: MEMORY配合环境变量传递这样流水线配置里不会出现任何敏感信息。第一次跑全自动 release 时我的JRELEASER_GPG_PASSPHRASE没有传给 Maven 插件进程结果签名阶段报GPG is not pinned这类难懂的信息。排查半天罪魁祸首是 GitHub Actions 里 secret 没有配置。所以你在搭流水线时请一定先确认这几个 secret 都存在GITHUB_TOKEN、GPG_PASSPHRASE、以及 Homebrew 用的个人访问令牌。4.3 macOS 安装包签名与公证问题jpackage 生成 dmg 后如果不做codesign和notarytool公证用户在 macOS 上首次打开就会被 Gatekeeper 拦下来。JReleaser 本身不负责签名 macOS 应用这块需要在 jpackage 之前做掉。我现在的思路是构建 job 里用codesign --deep --force签名应用再用xcrun notarytool submit上传公证最后才把它们打包成 dmg。JReleaser 只需要负责把 dmg 作为 artifact 上传。换句话说签名和公证这类依赖具体操作系统能力的事情交给原生构建步骤JReleaser 更擅长的是统一编排与分发。4.4 Homebrew formula 更新 PR 的目录敏感问题JReleaser 生成 Homebrew formula 时是根据 distribution 的platform字段来定位 macOS artifact 的。我的项目早期直接把platform: osx-x86_64写成了linux-x86_64导致 formula 里引用了一个不存在的下载链接PR 自动更新后 Homebrew 用户全部拉取失败。这里我给所有维护者一个重要提醒JReleaser 里的 platform 字段必须和实际构建目标严格一致。如果你在同一台 Mac 上同时构建 x86_64 和 arm64 的包务必给两个 artifact 标注不同的platform否则最后的发布产物会互相覆盖。4.5 校验和文件与 Release 附件的同步顺序默认情况下JReleaser 会生成checksums目录把每个 artifact 的 SHA-256 写进去。但这个文件的生成时机是在签名之后、上传之前。如果你用的 CI 任务里有「先上传 release 再上传 checksum」的步骤可能导致用户下载时 checksum 文件还没更新。我踩过一次让我们一起哇这句我怎么会说重新来。我踩过这个坑之后彻底放弃了自定义上传顺序完全交给 JReleaser 管理。它内部会把 checksum 作为 release 的一个附加资源一起上传顺序是受控的。如果你确实需要自定义钩子请确保你上传 release 附件的步骤依赖 checksum 生成完成而不是并行跑。5. 把发布流水线变成项目基础设施的一部分当整套发布流程稳定之后我开始考虑“让流水线自身也能生长”。JReleaser 的好处是它可以把发布逻辑沉淀到项目仓库里新人接手项目时不需要问“我们版本怎么发”只需要看一眼jreleaser.yml和 CI 配置就一目了然。5.1 版本策略与流水线触发条件我习惯采用 semantic versioning tag 触发的方式v1.0.0、v1.1.0-rc.1这种 tag 一推流水线自动跑。对于预发布版本JReleaser 支持prerelease字段可以直接在 release 配置里标记为true。release: github: prerelease: enabled: {{#tagMatches(release.tagName, .*(rc|beta|alpha).*)}}true{{/tagMatches}}这个 SpEL 模板表达式约等于规则引擎很灵活但也需要耐心调试。我的建议是先在 dry-run 里验证 tag 匹配逻辑再让正式流水线依赖它。5.2 发布门禁与可回滚性纯自动化固然爽但发布是影响所有用户的操作。我给流水线加了两道门禁在publishjob 之前加一个wait-for-approval环境只有项目维护者点击批准后才继续。这一点在 GitHub Actions 里用environment就能实现。在jreleaser:release之前先跑jreleaser:prepare它会生成发布草稿而不真正公开。审阅无误后再真正推送。这两道门禁让流水线在自动化之外保留了一个“人手确认”的刹车。尤其适合面向企业客户的工具一旦发错版本影响面可能非常大。5.3 我最后补充的三个小细节最后分享三个不起眼但很实用的小细节第一JReleaser 支持把announce阶段接到 Slack 或 Discord发布完成后自动推送消息。我把它接到项目群里发布状态瞬间同步比人工去群里喊一句“发好了”靠谱得多。第二在 Maven 项目里jreleaser:release的执行顺序一定要放在mvn package之后。我踩过把jreleaser:release写进package阶段导致每次构建都尝试发版的问题后来改成在 CI 里单独一行执行彻底解决。第三overwrite: true配置要慎用。如果发布已经公开覆盖行为虽然会更新 Release但某些分发商可能无法撤销已经推送的 Docker 镜像或 npm 包。稳妥的做法是失败后修改版本号重新走一遍流水线而不是直接覆盖。从手工发布到跑通这套流水线整个过程最大的收获不是“省了多少时间”而是发布这个动作变得可以预期。每次推 tag 后我只需要等待 CI 的绿灯亮起然后在发布页确认一下内容剩下的全部交给流水线。这种确定性比省下的几个小时更让人安心。如果你也在维护一个需要频繁发版的项目我真的建议你花一个下午把 JReleaser 接进来先跑通一个平台的流水线再逐步扩展跨平台分发。它会彻底改变你对“发布”这件事的理解。本文还有配套的精品资源点击获取