Zotero 插件开发入门：先理解结构与开发环境

写插件可以从很小的任务开始：给选中的条目显示一段信息，增加一个菜单动作，或者改善自己每天重复的步骤。先说清楚输入、操作与期望结果，再决定是否需要插件；若只是一次性查看数据，开发者菜单里的“运行 JavaScript”可能已经够用。本系列面向能读懂基础 JavaScript 的读者，不要求先掌握整个应用的内部代码。

从 Zotero 7 起发生了什么

旧教程常用 install.rdf 和 XUL overlay 注入界面。Zotero 7 起采用 manifest.json 描述插件，并以 bootstrap.js 管理生命周期。名称相似不代表普通浏览器扩展可以直接装进 Zotero：插件仍有自己的运行环境和可用能力。接触旧文章时，先看它针对哪个大版本，再决定代码能否参考。官方迁移说明解释了这些差别。

可以把插件理解为三部分：声明“我是谁、支持什么版本”的清单；在启动、禁用和窗口变化时登记或撤销功能的生命周期；真正完成任务的业务代码。添加菜单、监听器和偏好设置，都应同时想好退出时怎样清理。只关注启动成功，容易留下重复按钮或重复响应事件的问题。

版本起点要看实际文件

本系列于2026年11月10日核对文档。当前社区模板的清单声明最低 Zotero 8.0，最高11.*；这只说明模板声明的范围，并不证明你写的新功能已在这些版本全部测过。第2篇会固定所核对的源码快照。准备支持 Zotero 7 的读者，可从官方最小示例理解结构，再核实适用于7的工具版本。不能只把最低版本数字改小就宣布兼容。Zotero 8 的平台变化也有独立官方说明，新旧接口混用时应继续查证。

准备可独立丢弃的实验环境

安装 Git、代码编辑器和模板要求的 Node.js 版本。开发用 Zotero 与日常文库分开：配置目录保存设置和插件，数据目录保存数据库及附件，它们是两件事。新建配置后仍应检查数据目录，避免实验配置继续指向日常资料。只放几条测试文献和不重要的文件，先验证读取，再尝试写入。

开发环境不要登录日常同步账号。下载陌生插件或运行示例前先读来源和代码；插件能接触文库与计算机资源，安装成功不是安全证明。遇到问题也不要直接删除数据目录重来，应先确认自己正在操作实验目录。

先画一条最小路径

第一天的目标不是做完整设置页，而是完成一次可见动作，并确认禁用、重新启用及关闭窗口后行为合理。给每个实验记录 Zotero 版本、系统、模板提交号和复现步骤。一次只增加一个能力，就更容易知道问题来自环境还是刚写的代码。

建议先读清单和启动文件，再看一个菜单或界面示例，最后才碰批量修改。查资料时优先用官方开发文档、官方源代码和所用模板的原仓库。本文解释结构；具体命令、真实验证范围和下一步操作见第2篇。