Doc2X Zotero 插件使用指南
Doc2X Zotero 插件现已支持 Zotero 9。新安装用户建议使用 Zotero 9；如果暂时仍在使用 Zotero 7 或 8，请在下载页选择单独提供的兼容版插件。
版本支持
| Zotero 版本 | 插件版本选择 | 建议 |
|---|---|---|
| Zotero 9 | Zotero 9 | ✅ 推荐使用 |
| Zotero 7/8 | 兼容 7/8 | ⚠️ 仅建议存量环境短期过渡 |
| Zotero 6 | 无 | ❌ 不支持 |
注意：Zotero 9 版与 7/8 兼容版是两个不同的安装包，请根据当前 Zotero 主版本下载，不要混用。
安装前准备
安装和使用插件需要：
最新版插件已移除对 Better Notes for Zotero 的依赖，无需安装 Better Notes。
下载并安装插件
第一步：下载对应版本
- 打开 Doc2X 客户端与插件下载页。
- 找到“Zotero 插件”卡片。
- 根据 Zotero 版本选择插件：
- 使用 Zotero 9：保留默认选中的“Zotero 9”，点击“立即下载”。
- 使用 Zotero 7/8：切换到“兼容 7/8”，再点击“立即下载”。
- 下载完成后保留
.xpi文件，不要解压。
Zotero 9 推荐版
Zotero 7/8 兼容版
如果浏览器把
.xpi当作 Firefox 扩展打开，或提示文件损坏，请改用 Chrome 或 Edge 下载，并确认文件扩展名仍为.xpi。
第二步：在 Zotero 中安装
- 打开 Zotero。
- 进入“工具”→“插件”。
- 将刚下载的
.xpi文件直接拖入插件窗口。 - 如果无法拖入，点击插件管理器右上角的齿轮按钮，选择“Install Plugin From File…”（从文件安装插件），再选择
.xpi文件。 - 确认安装并按提示重启 Zotero。
安装完成后，可在插件列表中看到 Doc2X 插件。另请参阅 Zotero 官方插件安装说明。
更新已有插件
更新时请按以下顺序操作：
- 在 Zotero 插件管理器中卸载旧版 Doc2X 插件。
- 完全退出 Zotero。
- 重新打开 Zotero。
- 安装与当前 Zotero 主版本对应的新
.xpi文件。 - 再次重启 Zotero。
从 Zotero 7/8 升级到 Zotero 9 后，请卸载 7/8 兼容版，再安装 Zotero 9 版插件。
连接 Doc2X 客户端
第一步：安装并登录客户端
从下载页安装 Doc2X 客户端，启动后登录 Doc2X 账户。使用 Zotero 插件期间，请保持客户端运行。
第二步：获取 Token
- 打开 Zotero 设置：
- Windows：编辑 → 设置 → Doc2X。
- macOS：Zotero → 设置 → Doc2X。
- 也可以按
Ctrl/Cmd+,打开设置。
- 点击“获取 Token”。
- 插件会自动从本地运行的 Doc2X 客户端获取授权信息。
- 确认页面已显示 Token 状态和可用解析次数。
如果获取失败，请确认 Doc2X 客户端已启动并登录，然后重启 Doc2X 客户端和 Zotero 后重试。
配置解析与翻译
在 Zotero 的 Doc2X 设置页面中，可以配置以下选项。
翻译模型
插件支持免费和付费翻译模型。可用模型会从服务端动态加载，请以插件设置页面实际显示的内容为准。
- 免费模型：不消耗高级积分。
- 付费模型：按照页面显示的积分规则消耗高级积分。
目标语言
支持中文、英文、日语、法语、俄语、葡萄牙语、西班牙语、德语、韩语和阿拉伯语。
翻译忽略选项
可以选择翻译时忽略以下内容：
- 表格
- 代码
- 图片
- 文献
输出格式
- 文本输出：原文 MD、译文 MD、双语 MD、原文 HTML、译文 HTML、双语 HTML、译文 PDF、双语 PDF。
- 保留排版输出：原文 MD、保留排版译文 PDF、保留排版双语 PDF（原左译右或译左原右）。
术语表
可以选择自定义术语表，以保持专业术语翻译一致。设置完成后，勾选“我已完成解析和翻译配置”。
在 Zotero 中使用
在带有父条目的 PDF 附件上点击右键，即可看到 Doc2X 菜单：
- 翻译 PDF 为 Md 到笔记：翻译 PDF，并将结果作为 Markdown 笔记导入 Zotero。
- 解析 PDF 为 Md 到笔记：只解析 PDF，不进行翻译。
- 保留排版翻译：翻译 PDF 并保留原文排版。
- 打开报错日志目录：打开插件日志，便于排查问题。
对于已生成的笔记，还可以使用：
- Doc2X: 预览 Markdown：预览 Markdown 原文。
- Doc2X: 在网页中查看：在浏览器中打开解析或翻译结果。
费用说明
- 解析：消耗解析页数，当前解析折扣会自动应用，无需在插件中手动选择解析模型。
- 翻译：免费模型不消耗高级积分，付费模型按积分规则消耗高级积分。
如果解析已经完成，但翻译阶段失败：
- 在 Doc2X 客户端左侧任务栏中选择对应结果。
- 点击“继续翻译”。
- 完成后在客户端右上角选择导出到 Zotero。
这样只会继续计算翻译所需积分，不会再次扣除解析页数。不要在 Zotero 中重新发起同一个翻译任务。
使用注意事项
大文件
- 不建议直接在 Zotero 中翻译超过 100 页的 PDF。
- 长文档的插件状态更新可能不明显，可以在 Doc2X 客户端查看实时进度。
- 进度暂时没有变化不代表任务已经卡住。DeepSeek 等耗时较长的模型可能需要等待更久。
插件与客户端通信
插件通过 SSE（Server-Sent Events）与本地运行的 Doc2X 客户端通信，并会自动检测本地客户端端口。请保持客户端运行；连接中断后插件会自动尝试重连。
系统兼容性
| 操作系统 | 支持版本 | Zotero 版本 | 状态 |
|---|---|---|---|
| Windows | Win10/Win11 | Zotero 9 | ✅ 支持 |
| Windows | Win10/Win11 | Zotero 7/8 | ✅ 兼容 |
| Windows | Win10/Win11 | Zotero 6 | ❌ 不支持 |
| macOS | M 系列芯片 | Zotero 9 | ✅ 支持 |
| macOS | M 系列芯片 | Zotero 7/8 | ✅ 兼容 |
| macOS | Intel 芯片 | - | ❌ 暂不支持 |
视频教程
视频录制时使用的是旧版插件，其中包含安装 Better Notes 的步骤，也没有展示 Zotero 9 版下载入口。请以本文档的安装和版本选择说明为准。
常见问题
支持哪些 Zotero 版本？
推荐使用 Zotero 9；Zotero 7/8 可使用下载页中的兼容版；Zotero 6 不支持。
Zotero 9 可以安装“兼容 7/8”版本吗？
不建议。请为 Zotero 9 下载默认选中的“Zotero 9”版插件。两个安装包面向不同的 Zotero 主版本。
从 Zotero 7/8 升级到 Zotero 9 后插件不能使用怎么办？
先卸载 7/8 兼容版，完全退出并重新打开 Zotero，再安装 Zotero 9 版 .xpi 文件。
还需要安装 Better Notes 吗？
不需要。最新版 Doc2X 插件已移除对 Better Notes for Zotero 的依赖。
如何清除插件缓存？
在 Doc2X 插件设置页面点击“清除缓存”。此操作会重置插件设置，但保留授权信息。
插件无法连接到 Doc2X 客户端怎么办？
确认 Doc2X 客户端正在运行并已登录。插件会自动检测本地客户端端口并重试；如果仍无法连接，请重启 Doc2X 客户端和 Zotero 后重试。
问题反馈
如遇到其他问题，请联系我们。