JetStream VPN - 自由最快最稳妥, 亚洲最佳VPN返回首页

Zotero PDF2zh 怎么用？安装、首次翻译与 Network Error 排查

更新于 2026-11-02 · jetstream.mom

简答：一句话结论：Zotero PDF2zh 不是只安装 XPI 插件就能用，通常还要准备 Python 环境、启动本地 Server，并在 Zotero 的 Tools → PDF2zh Preferences 中配置服务地址和翻译服务。最短路径是：先核对发布版本，再选 uv 或 conda，启动 Server，安装匹配的 XPI，最后用一份可复制文字的短 PDF 测试。本文按 2026-11-02 检索到的项目发布页与文档整理；版本、模型、费用和兼容范围变化时，以当前页面为准。

定义：Zotero PDF2zh 是把 PDF2zh 或 pdf2zh_next 翻译流程接入 Zotero 的插件方案，插件负责 Zotero 内的入口和附件处理，Server 负责本地通信与翻译环境调用。

先看速查卡：第一次使用按这个顺序检查

如果你现在只想完成一次 PDF 翻译，不要先反复换模型或重装所有环境，按下面顺序逐项确认。

首次使用核验清单
环节应看到的状态不满足时的动作
发布版本插件 XPI 与 Server 来自同一发布版本打开项目 Releases 页面，重新确认版本和附件，不混用旧 XPI 与新 Server。
环境python --version、uv --version或conda --version至少一项可用修复命令路径后再启动 Server。
Server终端进程保持运行，没有启动后立即退出查看终端首个错误，确认目录、依赖和端口。
本地连接插件地址与 Server 的 host、port 完全一致以启动日志或当前配置文档显示的值为准，不要盲改地址。
PDF正文可以选中并复制扫描件先做 OCR；兼容选项不等于完整 OCR。
结果短 PDF 能生成新文件或新附件保留原文件，查看任务状态和终端日志，再判断是网络、模型还是排版问题。

项目当前发布页可核验到 v4.1.8 条目，发布时间显示为 2026-10-30；项目配置文档仍以 v4.1.1 配置说明为标题，因此版本号和配置字段应以你下载的发布包及当前文档共同核对，不能只凭旧教程判断。github.com

Zotero PDF2zh、PDF2zh 和 pdf2zh_next 怎么区分？

这几个名称不是同一个安装对象。Zotero PDF2zh 是 Zotero 集成插件；PDF2zh 和 pdf2zh_next 是插件可以调用的不同处理路径；配置文件、输出模式和可用选项可能随路径及版本变化。

组成主要作用判断方法
Zotero 插件提供菜单、设置、任务状态和附件导入在 Zotero 的 Tools 菜单中能否看到 PDF2zh 相关入口。
本地 Server接收插件请求，管理翻译环境并返回结果启动后进程持续运行，插件地址与监听地址一致。
pdf2zh旧版兼容路径通常使用旧配置格式；只有依赖旧功能时再考虑。
pdf2zh_next项目文档推荐的新路径通常使用 config.toml，具体能力以当前版本为准。
翻译服务实际生成译文检查 Base URL、模型、API Key、额度和限流规则。

当前配置文档把 pdf2zh 标为旧版兼容路径，把 pdf2zh_next 标为推荐路径，并列出配置文件、双栏布局、OCR、表格和术语相关差异；这些是文档中的版本化说明，不代表所有旧版本都具备相同菜单。github.com

安装前准备：Zotero、Python 与 uv 或 conda

  1. 确认 Zotero 桌面版能打开 PDF。先导入一份普通文本 PDF，确保附件本身可读。
  2. 确认 Python。项目安装说明推荐 Python 3.12；在终端执行 python --version，若系统使用另一命令，则检查 python3 --version。
  3. 只选一种环境工具。uv 适合按项目自动创建环境；conda 适合希望显式管理环境的用户。不要在同一个 Server 目录中来回切换。
  4. 准备独立目录。不要把 Server 解压到权限受限或经常移动的目录，避免路径变化造成环境找不到。
  5. 准备翻译服务资料。确认 Base URL、模型名称、API Key、请求限制和隐私条款。价格、免费额度、数据保留和是否用于训练，均需到具体服务商页面核实。

项目安装说明给出了 Python 3.12、uv、conda、server.zip 和 Zotero 插件安装路径，但不同发布版本的菜单与文件可能变化。安装时应优先使用发布页中的匹配附件，再对照项目安装说明检查命令。github.com

Windows、macOS、Linux：把 Server 启动起来

方案 A：使用 uv

项目说明提供了自动创建环境并安装依赖的启动方式。先进入解压后的 Server 目录，再执行：

uv run --with flask --with toml --with pypdf --with pymupdf --with packaging server.py

如果使用 Windows PowerShell，先执行 uv --version 确认命令可用；macOS 和 Linux 也先确认终端能识别 uv。若命令不存在，先安装 uv 并重新打开终端。

方案 B：使用 conda

conda create -n zotero-pdf2zh-server python=3.12 -y
conda activate zotero-pdf2zh-server
pip install -r requirements.txt
python server.py --env_tool=conda

项目安装说明要求按顺序执行 conda 创建、激活、安装依赖和启动步骤。Server 启动后不要关闭终端窗口，否则翻译功能会停止。github.com

插件安装与连接

  1. 从同一发布版本下载 XPI 与 Server 文件。
  2. 在 Zotero 中打开 Tools → Add-ons 或插件管理界面，把 XPI 拖入并按提示重启。
  3. 重启后打开 Tools → PDF2zh Preferences。
  4. 填写与 Server 实际监听值一致的地址。
  5. 先使用一份短 PDF 测试，不要直接处理重要的几十页扫描文档。

当前配置文档列出的默认 host 是 127.0.0.1，默认 port 是 8890；如果你修改了启动参数，插件地址也必须同步修改。由于文档和发布版本存在时间差，仍应以当前 Server 启动日志及配置为最终判定依据。github.com

插件配置和首次翻译：成功标准是什么？

  1. 在 PDF2zh Preferences 中确认 Server 地址可保存，且没有立即出现连接错误。
  2. 选择翻译引擎。没有旧功能依赖时，优先按当前文档尝试 pdf2zh_next。
  3. 在 LLM API 配置区域新增服务配置，填写服务商要求的 Base URL、模型和 API Key。
  4. 只启用一条配置，避免多个服务同时启用后无法判断实际调用对象。
  5. 选择一份可复制文字的短 PDF，先测试标题、摘要和一页正文。
  6. 观察 Zotero 任务状态、Server 终端输出和生成文件位置。
输出模式适合场景需要抽查的地方
单语译文只阅读译文标题、术语、参考文献是否被遗漏。
双语对照逐段核对原文分页、双栏顺序和长段落换行。
LR / 左右布局左右对照双栏论文是否出现页面顺序错乱。
TB / 上下布局上下查看原文和译文公式、表格和页脚是否被挤压。
Crop / 裁剪双栏或复杂页面页边、脚注和图注是否被截断。

本文不把上述模式的效果写成实测结论。建议用同一份短 PDF 建立记录：标题页、摘要页、含公式页、表格页、双栏交界页、参考文献页各抽查一页，并记录“文字顺序、公式、表格、脚注、页码、附件导入”六项结果。任何一项异常，先保留原 PDF，再切换输出模式或处理路径。

PDF 文本层、OCR、公式和注释：翻译前先做这项检查

如果正文无法选中，复制后得到空白或乱码，先把它当作扫描件或文本层损坏处理。项目配置文档明确说明，OCR workaround 主要改善已有文本层的扫描或特殊 PDF 兼容性，并不是完整 OCR 引擎；因此不能仅靠打开一个兼容选项解决所有扫描件。github.com

  • 扫描 PDF：先用独立 OCR 工具生成可搜索文本层，再用短页测试翻译。
  • 公式：抽查公式页，确认公式没有被当成普通句子改写。
  • 表格：抽查表头、单位、合并单元格和跨页表格。
  • 双栏排版：抽查栏间顺序，避免左栏末尾和右栏开头被串联。
  • 参考文献：检查作者、年份、DOI 和编号是否被翻译或截断。
  • 注释：Zotero 自建注释保存在数据库中；外部 PDF 注释默认可能是只读，可在 PDF 阅读器中使用 Import Annotations 导入后编辑。翻译前建议复制原附件。

Zotero 官方还区分了存储文件和链接文件：链接附件依赖本机路径，不能假定所有设备和插件流程都能同样访问。若插件找不到 PDF，先在 Zotero 中右键附件选择显示文件，确认文件真实存在，再判断是否需要转换为 Zotero 管理的存储副本。zotero.org

Network Error、端口冲突和环境找不到：按层排查

1. Network Error 或插件连接失败

  1. 确认 Server 终端仍在运行，且没有启动后立即退出。
  2. 确认插件地址与 Server 的 host、port 完全一致。
  3. 以当前启动日志显示的地址为准检查本机连接；不要默认所有版本都有相同状态页。
  4. 检查系统代理、防火墙和安全软件，确认本地回环地址没有被错误转发。
  5. 如果改过端口，必须同时修改 Server 启动参数和插件设置。

2. 查看端口占用

Windows 可在 PowerShell 执行：

Get-NetTCPConnection -LocalPort 8890 -ErrorAction SilentlyContinue

macOS 或 Linux 可执行：

lsof -nP -iTCP:8890 -sTCP:LISTEN

如果没有输出，可能是端口没有监听；如果显示其他进程，先确认是否是旧 Server，再决定关闭进程或更换端口。更换端口后要同步改插件地址。

3. 依赖、目录和 Python 不匹配

在 Server 目录重新检查 python --version、uv --version或conda info --envs。如果移动或重命名了 Server 文件夹，优先恢复原路径或重新建立环境，不要直接复制旧环境目录到新位置。

4. 翻译失败但 Server 正常

查看终端日志是否提示未授权、模型不存在、请求超限或上下文长度不足。若网络连接正常而只有部分段落失败，先换短 PDF 或减少处理范围，再判断服务参数，而不是立即重装插件。

升级、隐私和回退：什么时候应该停止继续尝试？

截至 2026-11-02，发布页列出 v4.1.8，并记录了与 Zotero 7 至 11 菜单兼容、窗口菜单和旧引擎依赖相关的更新；这只能说明发布记录中写明了这些变化，不能替代你对当前 Zotero 安装的实际验证。github.com

  1. 备份原始 PDF、Zotero 数据和当前配置。
  2. 记录旧插件版本、Server 目录、Python 或 conda 环境及启动命令。
  3. 下载同一发布版本的 XPI 与 Server。
  4. 不要直接覆盖唯一可用环境，先在独立目录启动新版。
  5. 用短 PDF 验证 Server、插件连接、API 配置和附件导入。
  6. 失败时停止新版进程，恢复旧插件、旧 Server 和旧配置，再单独定位变化点。

Server 默认绑定本机回环地址；若改用 --host 0.0.0.0，可能让同一网络内的其他设备访问，应同时设置防火墙和访问控制。API Key 不要放进公开截图、日志、普通网页或共享压缩包。若无法互相核对服务商的账户、费用、隐私条款或数据保留规则，应停止上传敏感文档和继续导入。

常见问题：安装前先把边界弄清楚

Zotero PDF2zh 必须安装 Python 吗？

按当前项目安装说明，通常需要 Python 环境或由项目管理的 Python 翻译环境；uv 和 conda 是两种环境管理路径。是否存在可完全免配置的独立包，应以当前发布附件说明为准。

插件和 Server 能不能分开升级？

不建议混用。发布包包含匹配的 XPI 与 Server，配置字段和通信行为可能变化。升级前备份旧环境，并用短 PDF 做回归测试。

为什么默认地址不能连接？

先看 Server 实际启动日志，再核对插件地址、host 和 port。当前配置文档列出 127.0.0.1:8890，但如果你改过端口、启动参数或使用了不同版本，必须以实际监听值为准。

扫描 PDF 能不能直接翻译？

如果 PDF 没有可识别文本层，不要把 OCR workaround 当成完整 OCR。先生成文本层，再用短页测试，必要时人工核对公式、表格和参考文献。

pdf2zh 和 pdf2zh_next 怎么选？

没有旧功能依赖时，可先按当前文档尝试 pdf2zh_next；需要旧配置或特定字体流程时，再核对旧路径是否仍被当前发布包支持。最终以当前设置页面和配置文件为准。

翻译服务是否一定收费？

不能一概而论。费用、额度、限流、数据保存和训练用途取决于具体服务商，本文没有统一价格结论，使用前应逐项核实。

常见问题

Zotero PDF2zh 的 Server 启动后可以关闭终端吗？

不能把它当成后台服务处理。当前安装说明要求保持 Python Server 进程运行；关闭启动窗口后，插件通常无法继续调用翻译功能。

Windows、macOS 和 Linux 的命令一样吗？

Server 的 Python 启动逻辑相近，但 uv 安装方式、终端命令、路径和权限可能不同。先确认当前系统能识别 Python 与环境工具，再执行项目提供的启动命令。

出现 Network Error 是网络线路问题吗？

不一定。优先检查 Server 是否运行、插件地址是否一致、端口是否监听、本机代理和防火墙是否干扰；这些属于本地连接层，不能直接归因于外部网络。

翻译后的 PDF 会覆盖原文件吗？

不要假定一定不会覆盖。升级或首次测试前先复制原始附件，并检查输出文件和附件导入结果；如果文件类型或路径异常，应停止批量处理。

Zotero 的注释会跟着翻译结果走吗？

不能一概而论。Zotero 自建注释保存在数据库中，外部 PDF 注释可能需要导入；翻译流程是否保留注释应以结果文件实际检查为准。

什么时候不适合继续安装？

如果发布版本、插件来源、账户条款、API Key 处理方式或服务商隐私政策无法互相核对，就不要继续下载、付款、上传敏感 PDF 或导入未知配置。

相关阅读

参考资料

  1. Zotero PDF2zh GitHub Releases：版本与发布记录
  2. Zotero PDF2zh 安装说明：Python、uv、conda、Server 与插件
  3. Zotero PDF2zh 配置说明：引擎、地址、端口与输出选项
  4. Zotero PDF2zh 项目文档首页：功能与安全默认设置
  5. Zotero 官方：添加与管理附件文件
  6. Zotero 官方：PDF 注释的存储与导入
  7. Zotero 官方：PDF 阅读器与注释