Zotero 插件打包发布：安装包、版本与更新清单

发布的目标不只是让别人下载到一个文件，还包括新用户能安装、老用户能更新，以及维护者能说明这次改变了什么。先在测试环境完成这些路径，再决定对外发布。本文解释已核对模板的流程，不会替读者执行提交、推送、打标签或创建公开版本。

从构建结果检查安装包

模板把源码和资源组合成 XPI。它本质上是带有规定目录结构的压缩包，而不是普通源码目录。本文所核对的模板快照15f7538c854d5f9751a470bf846389f744f9e920，于2026年11月10日使用 Node.js26.4.0、npm11.17.0构建通过，产物在 .scaffold/build/。

# 已验证：模板3.1.0；上述提交及 Node.js/npm 环境
npm run build

发布前打开构建后的清单，核对名称、插件标识、版本、最低和最高 Zotero 版本、图标与更新地址。检查是否还残留模板占位符，也检查示例功能和测试资源是否混入。能生成 XPI 不等于适配声明正确；实际支持的每个目标版本都需要安装和功能测试。

一个版本要能对上三处信息

源码中的版本、发布标签和安装包清单应表达同一次发布，用户看到的说明也要一致。模板可以协助生成这些内容，但你仍需要理解脚本会修改哪些文件、创建哪些标签和上传哪些产物。试验命令与正式发布命令不要混为一谈。

当前模板提供 npm run release。上游说明它会引导选择版本，并可能修改文件、创建提交与标签以及推送；仓库中的发布工作流还会继续构建和发布。该命令本篇未执行，真实发布行为待你在自己的仓库核实，不能把它当成无副作用的构建检查。先阅读 package.json、配置及工作流，再准备最小必要的发布权限，凭证不要写进源码。

更新清单是一条独立路径

插件清单中的 update_url 指向更新信息；更新信息再把某个版本指向实际 XPI。当前模板将常规版本与预发布版本的更新文件分别处理，并把更新文件放到专用 release 标签对应的发布资源里。具体地址应以自己仓库的构建结果为准，不照搬模板作者地址。

官方文档说明 JSON 更新清单中包含插件标识、版本和下载链接等信息。检查它是否能公开读取、返回真正的 JSON，以及下载链接是否指向同一个版本。若使用校验值，也要与实际上传文件一致。不要让更新清单提前指向尚未上传完成的文件。

兼容与升级分别验证

先用干净的实验配置安装新包，再在另一份实验环境装旧包，检查升级到新包的路径。升级后确认设置、菜单和既有内容仍能正常使用，并测试禁用后重新启用。预发布用户与常规用户也应各自走一遍，不让常规使用者意外收到试验版本。

发布说明只写用户能感知的变化与必要操作；维护者可以另附开发文档解释内部调整。保留可追溯的源码、构建环境与产物记录，出问题时先确认受影响版本，再决定停止提供有问题的更新或发布修复。不要无声覆盖同一版本安装包，让用户无法判断自己拿到哪份文件。