Skip to content

ZBridge 10.1.4

Choose a tag to compare

@taotaochen86 taotaochen86 released this 06 Nov 15:07

让本机网页(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 启动
  • 新增单元测试:test/unit.js 用 vm 造假 Zotero 环境,49 条断言,不装 Zotero 也能跑。
  • 构建脚本增强:build.py --bump 双写版本号(manifest + bootstrap),版本不一致直接报错。

⚠️ 插件版本号与 Zotero 版本号无关,是插件自己的递增序号。10.1.4 只表示迭代次数,
Zotero 从 10.0 升到 10.5 不需要动插件版本。


安装

  1. 下载本页下方的 zbridge-10.1.4.xpi(不要解压,它就是个 zip)
  2. Zotero → 工具 → 插件 → 右上角齿轮 ⚙ → 从文件安装插件…
  3. 选 zbridge-10.1.4.xpi → 弹窗提示未签名 → 点 安装
  4. 提示重启 → 立即重启(也可以直接拖 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。