jsPDF 版本发布全流程指南从 GitHub Release 到 npm 自动发布的标准化操作手册【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF本文以 jsPDF 官方仓库的 RELEASE.md 为骨架系统讲解维护者在发布新版本时执行的完整操作链路创建 GitHub Release 草稿、同步 bower.json 版本号、通过npm version打 Tag、推送分支以及最终由 GitHub Actions 在 Release 发布时自动触发npm publish。读者在阅读后可完整掌握 jsPDF乃至同类 npm 包的可复现发布流程并理解版本号在源码、构建产物与文档之间的传递机制。发布流程总览jsPDF 的发布流程是一个手动打 Tag CI 自动发布的混合模式版本号的更新与 Tag 的创建由维护者在本地完成而 npm 包的实际发布由 GitHub Actions 在 Release 正式发布时自动执行。整条链路如下在 GitHub 上新建一个draft release草稿 Release撰写并完善本次 Release 的版本说明Release Notes更新 bower.json 中的版本号仓库注释标注为TODO: Automate?即该步骤尚未自动化本地执行npm version 2.x.y同步更新 package.json 并生成 Git Taggit push origin v2.x.y推送版本 Taggit push origin master推送主分支代码在 GitHub 上将草稿 Release 正式发布此时 GitHub Actions 监听到release: published事件自动执行npm publish。这一设计的优势在于发布动作Publish由 CI 承担避免维护者在本地环境配置 npm 登录凭据同时保证发布包一定来自最新构建产物。步骤一创建 GitHub Draft Release发布的第一步是在 GitHub 仓库的 Releases 页面点击Draft a new release创建草稿。草稿不会对外可见维护者可以在此从容撰写说明。编写 Release Notes 时建议覆盖以下信息版本号与标题与后续npm version使用的版本号保持一致新增特性Features列出本次新增的 API 与模块例如新支持的图片格式、新的hotfixes选项等破坏性变更Breaking Changes明确提示使用者需要调整的调用方式Bug 修复Fixes列出修复的问题及其对应 issue/PR 编号升级指引说明从上一版本迁移的关键差异。草稿创建后先不要点击 Publish而是继续完成本地版本号更新与代码推送最后再回来发布草稿——这正是该流程将第 1、2 步与第 7 步拆开的原因。步骤二同步 bower.json 版本号jsPDF 仓库同时维护 package.json 与 bower.json 两份元数据。bower 生态虽然已逐渐淡出主流但仓库仍保留了对它的兼容因此发布前需要手动把 bower.json 中的version字段更新为目标版本{ name: jspdf, version: 4.2.1, description: PDF Document creation from JavaScript, main: [ dist/jspdf.umd.js, dist/jspdf.umd.min.js, dist/jspdf.es.js, dist/jspdf.es.min.js, dist/jspdf.node.js, dist/jspdf.node.min.js ], moduleType: [amd, globals, node, es6] }需要特别说明的是该步骤在 RELEASE.md 中被明确标注为TODO: Automate?即官方承认它尚未自动化需要发布者手工同步目前仓库中 package.json 与 bower.json 的版本号均为4.2.1两者保持一致是发布的前提之所以不能完全省略该文件是因为 bower 客户端在安装依赖时会读取此处的version与main字段来定位构建产物bower.json 中main字段列出的正是dist/目录下的 UMD、ESM、Node 三类打包文件。步骤三本地执行 npm version 更新版本号在仓库根目录执行npm version 2.x.y其中2.x.y替换为实际版本号遵循语义化版本 SemVer。npm version会自动完成三件事将 package.json 的version字段更新为指定版本生成对应的 Git Tag默认格式为v2.x.y触发 package.json 中定义的version生命周期脚本。version 脚本发布前的自动化构建与文档生成jsPDF 在 package.json 中为version脚本注入了发布前的关键动作version: yarpm run build yarpm run generate-docs git add -A dist docs其执行顺序为yarpm run build调用 rollup.config.js 重新构建所有分发产物产出dist/目录下的jspdf.umd.js、jspdf.es.js、jspdf.node.js及对应的.min.js压缩版本yarpm run generate-docs先由pregenerate-docs脚本deletedocs.js清理旧文档再调用 JSDoc 根据 jsdoc.json 配置源目录为src/输出到docs/重新生成 API 文档git add -A dist docs将重新构建的产物与文档自动暂存纳入本次版本提交。这意味着每次发版dist/构建产物与docs/文档都会与源码版本严格对应避免出现源码已更新但产物滞后的版本漂移问题。版本号在构建产物中的注入机制版本号并非硬编码在源码中。在 src/jspdf.js 中静态版本字段以占位符形式存在jsPDF.version 0.0.0;真正的版本号由 rollup.config.js 中的replaceVersion()插件在构建时注入function replaceVersion() { return replace({ delimiters: [, ], 0.0.0: pkg.version }); }即构建时从 package.json 读取pkg.version将源码中的0.0.0占位符替换为真实版本号。因此只要npm version更新了 package.json重新构建后的dist/产物就会携带正确的jsPDF.version。同理rollup.config.js 中的licenseBanner()会读取 src/license.js 模板把versionID版本号、builtOn构建时间与commitID当前 Git 短哈希写入每个产物的头部版权注释方便排查线上问题的来源。步骤四推送 Tag 与主分支版本号更新、构建与文档生成完成后依次推送两个引用git push origin v2.x.y # 推送版本 Tag git push origin master # 推送主分支含版本提交、dist 产物与 docs两个推送缺一不可Tag 推送v2.x.y是 GitHub Release 的关联锚点草稿 Release 需要指定目标 Tagmaster 推送确保主分支包含版本号更新提交、最新构建产物与文档保证仓库主干与发布版本一致。步骤五发布 Release触发 npm 自动发布回到 GitHub 上之前创建的草稿 Release将其正式发布Publish release。此时 GitHub Actions 工作流 .github/workflows/npm-publish.yml 会被事件自动触发name: Node.js Package on: release: types: [published] jobs: publish-npm: runs-on: ubuntu-latest steps: - uses: actions/checkoutv5 - uses: actions/setup-nodev6 with: node-version: 20 registry-url: https://registry.npmjs.org/ - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}该工作流的执行逻辑触发条件仅当 Release 状态变为published发布时运行draft草稿与prerelease状态不会触发环境准备检出代码、安装 Node.js 20、配置 npm 官方 registry 地址依赖安装npm ci依据 package-lock.json 安装锁定版本的依赖保证发布环境可复现发布动作npm publish使用仓库 Secrets 中的NPM_TOKEN进行 npm 身份认证并上传包。由于 package.json 的files字段仅包含dist、types/index.d.ts、README.md、LICENSEnpm 包内不会携带 src、test、examples 等目录实现精简发布。注意npm publish并不会重新构建它直接发布当前仓库即最新 master中已构建好的dist/产物。这正是步骤三中必须先跑 build的原因——保证发布出去的包与源码版本完全匹配。发布前的前置质量保障正式发版前维护者还应确保 CI 全绿。jsPDF 的持续集成工作流 .github/workflows/continuous-integration.yml 覆盖四类检查检查项内容对应命令Browser testsChromeHeadless 下的全量单元测试Karmanpm run test-ciNode.js testsNode 20/22 双版本下的测试Jasminenpm run test-nodeTypings testsTypeScript 4.0 与 latest 下的类型声明校验npm run test-typingsLintPrettier 格式一致性检查npm run lint在 package.json 中test脚本被定义为pretest先构建加test-node与test-ci的组合pretest: yarpm run build, test: yarpm run test-node yarpm run test-ci本地开发时也可使用npm run test-local一次性串行执行单元测试、Node 测试以及 AMD、ESM、Globals、TypeScript、WebWorker 五种部署形态的测试分别对应 test/deployment 下的 karma 配置。参考 PDF 基线文件位于 test/reference例如blank.pdf、textfield.pdf等用于像素级回归比对。发布流程中的关键约定与注意事项版本号一致性bower.json、package.json、Git Tag、GitHub Release 四处的版本号必须一致任何一处遗漏都会导致依赖解析或产物版本错乱Tag 格式Git Tag 使用v前缀如v4.2.1与npm version的默认行为一致发布是幂等动作的终点草稿阶段可以反复修改说明但一旦 Publishnpm publish会立即执行且 npm 不允许覆盖已发布的同版本号因此发布前务必确认版本号正确无需在本地配置 npm 凭据认证完全由 CI 中的NPM_TOKENSecret 承担维护者本地只需要 Git 权限版本号占位符机制若在源码中搜索不到真实版本号是因为 src/jspdf.js 中的0.0.0会在构建时被 rollup.config.js 的replaceVersion()替换为 package.json 的version字段。小结jsPDF 的发布流程是一条本地打 Tag、CI 发版的标准化流水线维护者只需在本地完成bower.json同步、npm version更新版本号与构建产物、推送 Tag 与 master随后在 GitHub 上发布草稿 Release剩下的npm publish由 .github/workflows/npm-publish.yml 自动完成。理解这一流程不仅可以帮助贡献者参与 jsPDF 的发版协作也能为其他 npm 开源项目的发布自动化设计提供可直接借鉴的范本。【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考