Joplin 发布部署全流程从 setupNewRelease 到各应用发布脚本的源码级解析【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 仓库同时维护桌面端、Android、iOS、CLI、Server、Web 剪藏器、插件生成器等多个可发布产物它们的版本对齐与发布流程被集中封装在packages/tools目录下的一组脚本中。本文基于仓库文档 DEPLOY.md 与对应发布脚本源码展开覆盖版本号统一设置、各应用发布命令的实际执行链路、changelog 自动写入机制等细节读完即可完整理解 Joplin 从“准备一个 minor 版本”到“各产物逐一发布”的全过程。一、发布脚本总览所有发布入口都定义在仓库根目录 package.json 的scripts字段中每个release*脚本最终都映射到packages/tools下的一个 Node 脚本yarn 脚本底层实现文件发布对象yarn setupNewReleasesetupNewRelease.ts全部包/配置版本号yarn releaseDesktoprelease-electron.ts桌面端CI 构建yarn releaseAndroidrelease-android.tsAndroid APKyarn releaseClirelease-cli.tsCLInpmyarn publishAllgulpfile.js 中completePublishAll全部joplin/*库npmyarn releaseServerrelease-server.tsJoplin Serveryarn releaseClipperrelease-clipper.tsWeb 剪藏器扩展yarn releasePluginGeneratorrelease-plugin-generator.js插件生成器npmyarn releasePluginRepoClirelease-plugin-repo-cli.ts插件仓库 CLInpm根目录 package.json 的engines字段声明了发布环境的最低要求Node22.12、Yarn4.14.1packageManager为yarn4.16.0。仓库通过 Yarn workspacespackages/*组织所有子包这是理解发布顺序依赖关系的前提。二、发布前置用 setupNewRelease 统一版本号按照 DEPLOY.md 的说明创建任何新发布之前都必须先更新全部版本号命令为yarn setupNewRelease 1.8该命令传入的是新的major.minor版本号patch 号在后续各包单独发布时自动递增。从源码 setupNewRelease.ts 可以看到它具体做了哪些事批量更新 19 个包的package.json脚本依次处理app-cli、app-desktop、app-mobile、generator-joplin、htmlpack、lib、pdf-viewer、plugin-repo-cli、react-native-alarm-notification、react-native-saf-x、renderer、server、tools、utils、onenote-converter、default-plugins、editor、transcribe、whisper-voice-typing将version字段设置为majorMinor.0同步内部依赖版本对每个包的dependencies和devDependencies中所有joplin/*前缀的依赖排除joplin/turndown、joplin/turndown-plugin-gfm和joplin/fork-*统一改写为~majorMinor形式更新原生工程配置Android改写 build.gradle 中的versionName为majorMinor.0iOS改写 project.pbxproj 中的MARKETING_VERSIONWeb 剪藏器更新 manifest.json 的version插件模板更新 generator-joplin 模板 manifest 的app_min_version保证新生成的插件以新大版本为最低兼容版本。几个值得注意的实现细节iOS 版本前缀 hack源码中的iosVersionHack函数会把x.y.z转成1x.y.z注释说明这是因为历史某次发布失误后App Store 不允许降低大版本号只能人为抬高可选参数通过--updateVersion0/--updateDependenciesVersion0可以只执行其中一类更新若两者都为 0 脚本会直接报 “Nothing to do!”脚本执行完毕会提示运行yarn install以刷新 lock 文件。以当前仓库状态为例app-cli/package.json 中joplin/lib、joplin/renderer、joplin/utils的依赖均写作~3.7与上述“依赖统一为 major.minor”的规则一致。三、桌面端releaseDesktop 依赖 CI本地只负责打 tagDEPLOY.md 描述桌面应用通过持续集成构建 Windows、macOS、Linux 三个平台的安装包触发方式是向 GitHub 推送版本 tag本地命令为yarn releaseDesktop对照 release-electron.ts 的源码这条命令的完整链路是gitPullTry拉取最新代码进入packages/app-desktop通过versionPatch()来自joplin/utils/version把当前包版本号的 patch 位加一作为本次发布的版本号git add -A、提交 “Desktop release version”、打同名的版本 tag 并git push --tags调用githubRelease(joplin, tagName, { isDraft: true, isPreRelease: true })在 GitHub 上创建一个草稿预发布真正的多平台构建与附件上传由 CI 在 tag 推送后完成打印后续操作提示用node packages/tools/git-changelog.js version生成 changelog并把版本更新合并回dev分支。也就是说本地命令本身不编译 Electron 应用它只负责“版本号 tag 草稿 release”这是理解 Joplin 桌面端发布模型的关键。四、AndroidreleaseAndroid 一条命令完成构建与上传yarn releaseAndroid --typeprerelease--type参数取值为release或prerelease。从 release-android.ts 看脚本的默认行为正是 prerelease不传--type时isPreRelease为true这与 DEPLOY.md 中“Android 只发布预发布版、后续再人工提升为稳定版”的注释一致。源码中这条命令的执行链路版本号自增直接改写 build.gradle——versionCode数字 1versionName的第三位patch1并以versionName生成 tagandroid-vversion构建 APK在仓库根目录依次执行yarn install、yarn tsc、yarn buildParallel然后在packages/app-mobile/android下运行./gradlew assembleRelease。源码注释特别说明不运行./gradlew clean因为在 React Native 0.8x 上clean会触发 CMake 重新生成并因 autolinking/codegen 失败改用yarn clean手动清理构建产物产物整理APK 从android/app/build/outputs/apk/release/app-release.apk复制到packages/app-mobile/dist/joplin-vversion.apk主渠道main还会额外复制一份joplin-latest.apk上传 GitHub Release在joplin-android项目下创建对应 tag 的 release并用 OAuth token 上传 APK写 changelog调用completeReleaseWithChangelog把本次改动写入 android.md。脚本还支持--release-name参数只构建指定渠道源码中定义了custom、armeabi-v7a、x86、arm64-v8a、x86_64等多个ReleaseConfig其中分架构构建目前处于disabled: true状态当前实际启用的是main与custom两个渠道。五、iOS手动使用 Xcode 发布DEPLOY.md 明确说明 iOS 应用必须使用 Xcode 手动构建并发布。仓库中版本对齐工作已由setupNewRelease完成更新MARKETING_VERSION发布动作本身则不在脚本自动化范围内。值得注意的是仓库里其实存在 release-ios.ts 脚本且根目录package.json中注册了releaseIOS从源码结构看可以推断该脚本承担的是与手动发布配套的部分流程如版本号或 changelog 处理但 DEPLOY.md 的口径仍以 Xcode 手动发布为准。六、CLI先 publishAll 发布全部内部库再发 CLI 本体DEPLOY.md 指出 CLI 与移动端/桌面端不同它不打包依赖始终从 npm 源码安装因此所有joplin/*依赖必须先公开发布。这一步由publishAll完成yarn publishAll对照根目录 package.jsonpublishAll的完整定义为git pull yarn buildParallel lerna version --yes --no-private --no-git-tag-version gulp completePublishAll拆解为四步git pull拉取最新代码yarn buildParallel并行构建全部 workspace 包底层是yarn workspaces foreach ... run build yarn tsclerna version --yes --no-private --no-git-tag-version为所有非 private 的joplin/*包提升 patch 版本号不自动打 taggulp completePublishAll执行 gulpfile.js 中定义的任务git commit版本变更 →lerna publish from-package -y --no-verify-access发布所有包注释解释了--no-verify-access是为绕过自动化 token 下 Lerna 的多余鉴权检查参见 lerna issue #2788→yarn install并再次提交 lock 文件 →git push。这一步会发布joplin/lib、joplin/renderer、joplin/utils、joplin/tools等全部 Joplin 内部库。接下来按 DEPLOY.md 的要求在 app-cli/package.json 中把所有joplin的dependencies和devDependencies设置为新的 major/minor 版本例如1.8当前仓库实际值为~3.7dependencies: { joplin/lib: 1.8, joplin/renderer: 1.8, ...: ... }, devDependencies: { joplin/tools: 1.8, ...: ... }最后发布 CLI 本体yarn releaseClirelease-cli.ts 的执行流程git pull→versionPatch()自增版本并生成 tagcli-version→ 进入packages/app-cli执行yarn build即gulp build并复制 README 到build/→ 在build/目录中npm publish→ 调用completeReleaseWithChangelog把 changelog 写入 cli.md。脚本头注释还提到可用node packages/tools/release-cli.js --changelog-from cli-vX.Y.Z手动指定 changelog 的起始 tag。七、Joplin ServerreleaseServeryarn releaseServerrelease-server.ts 的链路相对简洁gitPullTry→ 进入packages/server→versionPatch()自增版本 → 生成 tagserver-version→completeReleaseWithChangelog把 changelog 写入 server.md。tag 推送后由 CI 完成 Server 的实际构建镜像构建相关脚本见 buildServerDocker.ts本地命令同样只负责版本与 tag。八、Web 剪藏器releaseClipperyarn releaseClipperrelease-clipper.ts 的完整流程自增版本号读取 manifest.json把version的最后一位build number加一并写回构建扩展切换util/joplinEnv.mjs为prod模式该文件被标记为// AUTOGENERATED by release-clipper在packages/app-clipper/popup下npm run build生成双平台发行包分别组装dist/chrome与dist/firefox两者的差异在manifest.json上——Chrome 包删除browser_specific_settings并去掉background.scripts/persistent使用 MV3 service workerFirefox 包则删除background.service_worker使用 scripts 形式随后各打成一个 zip源码包校验额外打一个joplin-webclipper-source.zip排除node_modules/、build/、dist/用于浏览器商店的代码审查并且脚本会在临时目录里重新npm install npm run build逐文件比对重新编译结果与已发布的 Firefox 包MD5 对比确保“发布的二进制与开源源码可复现一致”打 tag若无--no-publish参数则git commitgit tag clipper-version 推送最后把joplinEnv.mjs切回dev模式。九、插件生成器与插件仓库 CLI插件生成器generator-joplin按 DEPLOY.md发布前一般先更新类型定义./updateTypes.sh然后yarn releasePluginGeneratorrelease-plugin-generator.js 的自动化程度较高进入packages/generator-joplin后它会自己执行一次bash updateTypes.shversionPatch()自增版本把package.json的private字段临时去掉setPackagePrivateField以允许npm publishfinally中保证恢复为true最后提交、打 tagplugin-generator-version并推送。仓库根目录package.json中还注册了updatePluginTypes脚本指向 updateTypes.sh。插件仓库 CLIplugin-repo-cliDEPLOY.md 说明该工具用 Webpack 打包因此单条命令即可发布yarn releasePluginRepoCli对照 release-plugin-repo-cli.ts根目录yarn tsc编译类型 → 进入packages/plugin-repo-cli执行yarn dist即 package.json 中定义的webpack --config webpack.config.js→versionPatch()自增版本 →npm publish→ 打印plugin-repo-cli-versiontag 对应的收尾 git 命令。十、通用收尾机制changelog 自动写入与收尾命令多个发布脚本CLI、Android、Server 等结尾都会调用 tool-utils.ts 中的completeReleaseWithChangelog它的工作方式是执行node packages/tools/git-changelog tag --publish-format full从 git 提交记录生成该版本的变更清单实现见 git-changelog.ts将结果以## tag加 UTC 时间戳的格式插入到对应 changelog 文件顶部各产物对应 changelog 目录 下的cli.md、android.md、server.md等文件打印提示先用$EDITOR人工核对 changelog再执行releaseFinalGitCommands生成的收尾命令链——git add -A git commit -m AppName version git tag tag git push git push origin refs/tags/tag这解释了 Joplin 发布的最后一个共性环节脚本负责构建、发布、写 changelog而最终的版本 tag 提交普遍需要人工核对后执行桌面端例外它在脚本内直接完成了 tag 与 push。小结Joplin 的发布体系可以概括为三层版本层setupNewRelease一次性对齐 19 个 npm 包、Gradle、Xcode、剪藏器 manifest 与插件模板的版本号patch 号留待各包发布时自动递增发布层每个产物对应packages/tools/release-*.ts脚本桌面端与 Server 走“本地打 tag CI 构建”Android/CLI/插件工具走“本地构建 直接上传/npm publish”CLI 发布前必须通过publishAllLerna 驱动先把全部joplin/*库发布到 npm收尾层completeReleaseWithChangelog统一处理 changelog 写入与收尾 git 命令人负责最终核对。所有命令的适用前提与 DEPLOY.md 一致需在完整的 Joplin monorepo 根目录下执行且环境满足根 package.json 声明的 Node/Yarn 版本要求。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考