Repository navigation
ZBridge 10.1.4
让本机网页(WPS / Office 加载项、file:// 页面、本地 Web 应用)直连 Zotero,不需要任何中继进程。
Zotero 自带的 HTTP server 对浏览器来源有三道拦截(断连、不给 CORS 头、预检短路),
ZBridge 注册自己的端点把这三件事处理掉,于是浏览器里的加载项终于能直接调 Zotero。
本次更新(10.1.4)
- 清单改为
strict_max_version: "*":Zotero 7.0 以上全系列可安装,不再被版本号拦住。- 10.0 / 10.0.x / 10.1 / 10.2 / 10.5 / 10.99 均可,已实测 10.0.7。
- 代码里没有任何版本分支判断,只依赖
Zotero.Server.Endpoints、init(request)→[status, headers, body]契约、allowRequestsFromUnsafeWebContent——这三样从 Zotero 7 到 10 一直没变。
- 三处兼容兜底,不再只按 10.0.7 写死:
- query 参数载体:
request.searchParams→ 回退request.query - 请求体:UTF-8 字符串 → 回退字节数组
TextDecoder转码 Zotero.Server.Endpoints缺失:只写日志、跳过注册,绝不抛异常拖垮 Zotero 启动
- query 参数载体:
- 新增单元测试:
test/unit.js用vm造假 Zotero 环境,49 条断言,不装 Zotero 也能跑。 - 构建脚本增强:
build.py --bump双写版本号(manifest + bootstrap),版本不一致直接报错。
⚠️ 插件版本号与 Zotero 版本号无关,是插件自己的递增序号。10.1.4只表示迭代次数,
Zotero 从 10.0 升到 10.5 不需要动插件版本。
安装
- 下载本页下方的
zbridge-10.1.4.xpi(不要解压,它就是个 zip) - Zotero → 工具 → 插件 → 右上角齿轮 ⚙ → 从文件安装插件…
- 选
zbridge-10.1.4.xpi→ 弹窗提示未签名 → 点 安装 - 提示重启 → 立即重启(也可以直接拖 xpi 到插件窗口,效果相同)
不需要管理员权限,不联网,不占额外端口,没有独立进程。
装完验证(三步,全过才算装好)
TOKEN=e3b6034fbdd85456f5ac6df1a4e54ef4 # 没改过就用默认值① 端点活着(不需要令牌)
curl -s "http://127.0.0.1:23119/zbridge/ping"期望:
{"name":"ZBridge","version":"10.1.4","zotero":"10.0.7","minZotero":"7.0","compat":"Zotero 7.0+ (verified on 10.0.7)","endpoints":["/zbridge/execute","/zbridge/ping"]}zotero 是你本机实际版本,version 是插件版本,两者无关。
② 能执行 JS
curl -s -X POST "http://127.0.0.1:23119/zbridge/execute?token=$TOKEN" \
-H "Content-Type: text/plain" --data-binary 'return 1+1'期望返回 2。
③ 模拟浏览器来源(这一步才是 ZBridge 存在的意义)
curl -s -X POST "http://127.0.0.1:23119/zbridge/execute?token=$TOKEN" \
-H "Content-Type: text/plain" -H "Origin: null" --data-binary 'return Zotero.version'期望返回你本机的 Zotero 版本串。
安全说明
- 端点只监听
127.0.0.1,外网访问不到。 /zbridge/execute必须带?token=,令牌存在 Zotero 配置项extensions.zotero.zbridge.token,改完即时生效、不用重启。/zbridge/ping有意不校验令牌,只回版本信息,方便排障——不要拿它当作鉴权测试。- 令牌走 query 而非自定义头,是为了让请求成为「简单请求」、不触发 CORS 预检。
文件校验
zbridge-10.1.4.xpi
sha256: d92f0a7b3f826dba1d5d04bca26b042d9f302449e337711406bba83b0fe41921
update.json 里的 update_hash 与此一致,Zotero 自动更新会校验它。
完整文档
安装详细步骤(含升级、卸载、故障排查表)、英文说明、构建方法:见 README。