简介面向Zotero文献管理用户与科研写作人群的scite插件源码包用于在Zotero文献列表中直接呈现scite的Smart Citation引文分类数据帮助读者快速判断一篇论文是被后续研究支持、提及还是质疑。安装后每条文献记录会显示Supporting、Mentioning与Contrasting三列计数并可一键跳转至scite站点查看详细报告页适合需要评估文献证据强度、开展综述写作的研究生与高年级本科生使用。资源共31个文件压缩包约1.24MB以TypeScript源码为主体配合package.json、tsconfig.json、tslint.json等工程配置以及itemPane.xul、zoteroPane.xul等界面定义、locale本地化文件与png示例截图构成一个可直接构建调试的Zotero插件工程。该资源已有1166人学习下载读者可从中获得插件入口逻辑、面板注入与猴子补丁等实现思路参照示例截图理解引文分类栏的展示效果并借助README与webpack配置完成本地编译与功能验证是研究Zotero扩展开发与文献计量工具集成的实用参考。1. 明明装上了却不工作一次因 TypeScript 工具链版本不一致而失败的记录Zotero 里装 scite 插件最容易出问题的地方往往不在插件本身而在本地那套 TypeScript 工具链Node 版本太老、tsconfig 的 target 写到 ES2022、打包器又把类型检查吞了最后插件列表里能看到名字条目右侧的引文报告面板却一直空白日志里连报错都不给像个无法查看内部状态的黑匣子。这套环境要同时对齐 Node、npm、TypeScript、打包器和 Zotero 本体这五个组件装不好的直接结果就是白折腾一晚上还以为插件坏了。它适合天天读文献、想在条目上直接看到某条引用是被后续研究支持还是存在争议的人也适合要改源码加自己逻辑的开发者。2. 环境准备Node 20、Zotero 7 与 TypeScript 5 的版本对照装插件和装一个普通 npm 包完全不是一回事。普通前端项目只要浏览器能跑就行而 Zotero 插件跑在 Zotero 内嵌的那份运行时里你的 TypeScript 编出来的语法级别、打包出来的模块格式、manifest 里声明的兼容区间三者只要有一个对不上Zotero 就会安静地不加载或者加载了但功能不生效。我一般先把这三份版本关系摆到纸面上再动手省得来回试。2.1 Node 与包管理器的版本选择Node 这块没有太多可纠结的选 20 LTS 就够。18 也能跑但 18 已经进入维护末期部分新版本的打包器会要求更高的 Node 版本22 反而要小心某些带原生模块的依赖在 22 上编译工具链还没跟上npm install卡在编译阶段十几分钟不动的情况我遇到过不止一次。所以别用系统自带的那份 Node用版本管理器固定住。# 用 nvm 固定 Node 大版本避免系统自带的 Node 混进来 nvm install 20 nvm use 20 node -v # 期望 v20.x.x npm -v # 期望 10.x npm config get registry # 确认没有指向一个已经失效的内网镜像nvm use只对当前 shell 生效换一个终端窗口就回到默认版本了所以每次开新窗口编译前先node -v确认一下这一步看着傻但能省很多事。npm config get registry是我血泪经验里加的一条很多人机器上残留着几年前配的公司内网镜像那个地址早就下线了表现是npm install一直挂在那儿没输出既不是网络问题也不是权限问题。包管理器用 npm 或 pnpm 都行但只要仓库里带了package-lock.json就别混着用。npm 和 pnpm 的依赖提升策略不一样混用最容易出现的现象是本地能 build、换台机器就报模块找不到。2.2 Zotero 版本与插件兼容范围scite 这个插件在 Zotero 6 和 Zotero 7 上走的是两套 API 路线6 时代靠 overlay 方式挂载界面元素7 改成了引导式启动加模块化加载源码分支、构建产物、manifest 字段都不一样。所以第一件事是确认你手上是哪个版本的 Zotero再决定拉哪个分支。Zotero 版本manifest 中 strict_min_versionstrict_max_version说明6.0.x6.06.0.*旧版挂载方式插件源码不是同一套7.0.x6.9997.0.*引导式启动TypeScript 构建产物的主目标6.999这个值第一次看到会觉得是写错了其实是上游约定Zotero 7 的版本号从 7.0 起用6.999当 min 就能同时覆盖 6 的尾部和 7 的开头。如果你把 min 写成7.0那在 7.0 的早期 beta 上会判定不兼容写成6.0又会把 6 拉进来而 6 上这份代码根本跑不起来。max 写成7.0.*而不是7.*是为了避免 Zotero 未来大版本改动后插件被自动加载然后崩掉。提示改完 manifest 里的兼容区间一定要重新打包直接改已安装目录里的 manifest 会在下次启动时被覆盖。2.3 package.json 与目录结构里必须确认的字段源码根目录下这份配置是整个构建流程的入口。不同仓库的字段名会略有出入但下面这几项基本都会出现装之前挨个对一遍比出了错再回头翻要快得多。{ name: scite-zotero-plugin, version: 0.1.0, type: module, config: { // 插件的唯一标识代理文件和 extensions 目录都靠它对齐 addonID: scite-zoterolocal.test, // 简称构建时用来拼产物目录名和资源路径 addonRef: scitezotero, // 偏好项前缀写错的话设置面板里改了不生效 prefsPrefix: extensions.zotero.scitezotero }, scripts: { build: tsc --noEmit zotero-plugin-scaffold build, start: zotero-plugin-scaffold start } }addonID是这一组字段里最关键的一个代理文件要以它命名已安装插件的目录也以它命名改一次就要清一次旧目录否则会出现新旧两份同时被加载的怪现象。addonRef一般全小写无连字符构建脚本用它拼输出路径。prefsPrefix决定你后面在配置编辑器里看到的偏好项全名很多“设置里改了没反应”的问题最后都追到这三个字段没对齐。目录结构上src/放 TypeScript 源码addon/放 manifest、图标、locale 这类不参与编译的静态资源构建产物落在build/下。build/不要提交到仓库它每次构建都会被覆盖冲突起来非常难受。3. 拉取源码与构建从 clone 到出 xpi 的完整命令环境对齐之后才是真正动手。这一段我按顺序走一遍拿代码、装依赖、改编译配置、打包每一步都给出失败时该看哪里。整个流程在一台干净机器上大概十分钟卡住基本都卡在依赖和类型检查这两处。3.1 获取源码与安装依赖先确认分支再 clone别默认拉主分支然后发现是 Zotero 6 的代码。# 拉代码目录名自己定别用中文和空格 git clone 仓库地址 scite-zotero-plugin cd scite-zotero-plugin # Zotero 7 的代码通常在 main 或 zotero7 分支上先看一眼 git branch -a git checkout main # 有 lock 文件就优先用 ci它严格按锁文件装不会偷偷升级 npm cinpm ci和npm install的差别值得说一句ci会先删掉node_modules再按package-lock.json精确安装装出来的依赖树和你同事机器上完全一致install会尝试解析语义化版本范围可能把某个次版本升上去然后你就得到一个“只有我这台机器编译不过”的问题。仓库里没有锁文件时只能用install那装完记得把生成的锁文件一起提交。依赖装完看一眼node_modules/zotero-types在不在。这个包提供 Zotero 全局对象Zotero、Services、XPCOM那些的类型声明缺了它后面tsc会一次性报几十个“找不到名称 Zotero”看着吓人其实只是没装上。3.2 tsconfig 与构建脚本的取舍TypeScript 配置这一块很多人是从别的项目复制过来的target随手写着 ES2022 甚至 ESNext本地跑得好好的装进 Zotero 就静默失败。Zotero 7 内嵌的运行时对应 Firefox 115 左右ES2020 是稳妥的选择。{ compilerOptions: { // 别写到 ES2022 以上Zotero 内嵌运行时不认新语法 target: ES2020, module: ESNext, moduleResolution: Bundler, lib: [ES2020, DOM], // 打开严格模式Zotero 的全局对象大多是可空的早报错早改 strict: true, // 产物交给打包器生成tsc 只做类型检查 noEmit: true, types: [zotero-types], baseUrl: ., paths: { /*: [src/*] } }, include: [src/**/*.ts, typings/**/*.d.ts] }noEmit: true是这份配置里最容易被误解的一项。它意味着编译产物不归tsc管真正生成 JS 的是后面的打包器esbuild 之类。这样做的好处是构建快坏处是打包器默认不做类型检查类型错了照样能打出包来运行时才炸。所以package.json里的build脚本要写成tsc --noEmit ...先过一遍类型再打包类型不过直接中断别让错误流到产物里。moduleResolution: Bundler允许省略后缀写 import前提是确实有打包器在处理模块解析。如果你把它改成Node源码里那些不带后缀的相对导入会集体报错。strict: true加上之后一开始会有大量报错尤其是从Zotero.Items.get()这类返回可空值的地方取值。别急着关掉把strict关了等于把运行时可能的空指针挪到用户那边去暴露。3.3 打包产物与本地安装# 先类型检查再打包产物默认在 build/ 下 npm run build # 确认产物真的生成了顺手看下大小 ls -lh build/*.xpibuild目录里通常会有两份东西一份是打包好的.xpi一份是解包后的插件目录。后者是给开发模式用的等下会讲到。安装走 Zotero 的插件管理界面工具 → 插件 → 右上角齿轮 → 从文件安装选中那个.xpi。这里有个前置条件自己构建出来的包没有签名Zotero 7 默认拒装未签名插件需要在“设置 → 高级 → 配置编辑器”里把xpinstall.signatures.required设为false。注意这一项只在你自己的开发机上改改完记得记下来别在共用机器上留这个状态。装完必须重启 Zotero插件列表里才会出现条目。如果装完列表里显示“不兼容”回到 2.2 节检查strict_max_version这是最高频的原因。4. 配置插件参数报告面板、偏好项与开发模式热加载到这里插件能装上了但装上不等于好用。scite 这个插件的核心行为是把某条文献的引用情况去服务端查一次然后在界面上渲染成报告。查什么、什么时候查、结果缓存多久、面板出现在哪儿这些都由偏好项控制配错了就是“插件在、数据不在”的状态。4.1 偏好项面板位置、超时与缓存偏好项分两层代码里的默认值走prefs.js运行时用户改过的值落在配置目录的prefs文件里。默认值只需要写一次不用自己去读写存储。// prefs.js —— 这里只放默认值运行时修改由偏好系统接管 pref(extensions.zotero.scitezotero.panelPosition, sidebar); pref(extensions.zotero.scitezotero.requestTimeout, 8000); pref(extensions.zotero.scitezotero.cacheTTL, 86400); pref(extensions.zotero.scitezotero.autoFetch, true);panelPosition决定报告渲染在条目侧栏还是独立窗口。侧栏的好处是不打断阅读缺点是窄屏上会把条目信息挤得很紧我一般在笔记本上改成独立窗口。requestTimeout单位是毫秒8000 是个折中值写太小在网络抖动时会把本来能回来的请求掐掉写太大则面板一直转圈用户以为卡死了。cacheTTL单位是秒86400 即一天同一个条目反复点开时命中缓存直接出结果能明显减少等待——这类数据一天内基本不会变缓存久一点没有副作用。autoFetch控制是选中条目就自动查还是点按钮才查前者省事后者省流量。改完之后到“设置 → 高级 → 配置编辑器”里搜scitezotero就能看到这几项值类型是布尔就填true/false是整数就直接填数字别加引号。这里最常见的错误是前缀写错比如prefsPrefix配的是extensions.zotero.scitezotero而prefs.js里手写成了别的结果设置面板里怎么改都没反应因为读的根本不是同一个键。4.2 开发模式代理文件与 watch 构建每次改代码都打包、安装、重启一轮下来两分钟改十次就受不了。开发模式下可以绕过.xpi让 Zotero 直接加载源码构建出来的目录。# 1) 先完整构建一次保证解包目录里有完整产物 npm run build # 2) 找到当前 Zotero 配置目录 # 帮助 → 更多故障排除信息 → 打开配置文件夹 # 3) 在 profile/extensions/ 下建一个纯文本文件 # 文件名就是 addonID内容只有一行构建产物目录的绝对路径 echo /abs/path/to/scite-zotero-plugin/build/addon \ profile/extensions/scite-zoterolocal.test几个细节文件名必须和manifest.json里的applications.zotero.id完全一致差一个字符就不生效文件内容只有路径前后不要有空格和换行之外的东西文件没有后缀不是.txt。做对了之后Zotero 启动时会把那个目录当成已安装的插件读进去你改完源码重新构建、重启一次即可跳过打包和安装两步。配合npm run start可以进一步省掉手动重启这类脚手架一般会监听源码变化重新构建并在检测到 Zotero 在跑时通过调试桥触发重载。第一次跑之前要在 Zotero 里打开调试输出启动参数加-ZoteroDebugText -jsconsole否则你只能看到界面没反应不知道是没重载还是重载了但报错。提示交付前一定要把自己配置目录下的这个代理文件删掉否则你本机装正式包时会和源码目录里的版本打架。4.3 三个路径别搞混排查问题时十次有六次是路径搞错了改了配置却在另一个目录里找或者以为清了缓存其实清的是别处。路径怎么找里面有什么配置目录profile帮助 → 更多故障排除信息 → 打开配置文件夹prefs、extensions/、调试日志数据目录设置 → 高级 → 文件和文件夹zotero.sqlite、storage/下的附件构建产物目录仓库下build/.xpi与解包后的插件目录配置目录和数据目录可以是同一个也可以分开——很多人为了把数据放同步盘单独改过数据目录位置。这种情况下你清插件缓存要清配置目录里的那部分别去数据目录翻。构建产物目录则完全独立于 Zotero删了重新npm run build就行不会影响已安装的插件。5. 常见问题排查构建失败、不加载、面板空白的五条踩坑记录这一段是我自己反复遇到的几个问题按“现象 → 原因 → 解决”记下来。前三条在构建阶段后两条在运行阶段。5.1 构建与依赖阶段现象一npm install卡在编译原生模块十分钟没动静。原因通常是 Node 版本和某个依赖要求的不一致或者机器上缺 C 编译工具链Windows 上缺 Visual Studio Build ToolsmacOS 上缺 Xcode Command Line Tools。先换到 Node 20 再试还不行就装工具链。实在过不去把node_modules和锁文件一起删掉重来别在残留状态上反复试。现象二npm run build报一堆TS2307 Cannot find module zotero-types或“找不到名称 Zotero”。tsconfig.json里的types数组没写zotero-types或者依赖根本没装上。先ls node_modules/zotero-types确认包在不在不在就重新npm ci在的话检查types字段注意它是个数组。现象三构建成功但.xpi装上去显示“不兼容”。manifest 里的strict_max_version比当前 Zotero 版本低。Zotero 7.0.x 要把 max 写成7.0.*min 写6.999。改完记得重新打包不要改已安装目录里的那份。5.2 加载与运行阶段现象四插件列表里有它选中文献后报告面板一片空白日志里没有明显报错。多半是请求没发出去或者回来了但被吞了。先在调试器里看网络请求有没有真的发起如果压根没发检查autoFetch和触发逻辑如果发了但状态异常常见原因是请求超时设得太短、或者服务端返回结构和你解析的字段对不上。把requestTimeout临时调到 20000 试一次能出来就说明是超时问题。现象五改了代码重启 Zotero 后行为没变。两种可能一是构建产物没更新npm run start的 watch 进程挂了或者你根本没跑手动npm run build一次再重启就能验证二是代理文件和已安装的.xpi同时存在Zotero 加载的是后者。去配置目录的extensions/下看看有没有以插件 ID 命名的目录有就先删掉只保留代理文件这一条路。6. 装完怎么验证三个动作确认插件真的跑通我不太信“插件出现在列表里就算装好了”这个判断标准。列表里出现只说明 manifest 解析通过功能链路可能一寸都没走通。所以装完我会按下面三个动作过一遍每个动作对应链路上的一环哪一环断了能直接定位。第一个动作看版本号和自检输出。打开工具 → 插件找到这个插件确认显示的版本号和你刚构建的package.json里的version一致。不一致就说明加载的还是旧的那份先解决这个问题再往下走。然后在调试控制台里看启动日志正常情况会有插件初始化、偏好项读取、命令注册这几行输出缺哪一行就说明对应模块没跑起来。第二个动作拿一条真实文献试完整链路。在文献库里选一条有引文数据的条目打开报告面板观察三件事面板有没有出现、有没有 loading 状态、最终有没有渲染出内容。我一般会特意挑一条被引次数多的数据量足够能顺带看出渲染性能。如果面板出现但一直是 loading回到 5.2 的第四条如果渲染出来了但数字明显不对那就是字段解析的问题去对比接口返回的原始结构。验证动作预期结果常见失败点查版本号与构建版本一致代理文件与已装 xpi 并存打开报告面板出现 loading 后渲染出内容超时过短、解析字段错位断网再打开一次命中缓存秒出或给出明确错误提示无兜底直接空白第三个动作是故意制造异常。把网络断开再打开一次同一条文献的报告面板预期是命中缓存直接出结果或者给出一个用户能看懂的错误提示。这一步是我从一次线上反馈里学来的正常情况下什么都看不出来一断网就暴露了——面板白着转圈转到天荒地老用户只会认为插件坏了。加上超时兜底和错误文案之后同样的场景用户知道是网络问题不会跑来问你是不是插件有 bug。从那以后我每次装完这类带远程请求的插件都强制走一遍断网路径哪怕它看起来浪费时间。装环境这件事能把失败路径也跑一遍才算真的装完了。希望帮到你。本文还有配套的精品资源点击获取