在上一篇文章中，我们介绍了如何在 Windows 环境下搭建：

Zotero + PDF2zh + AI 翻译 API

双语 PDF 翻译环境。

但是对于第一次使用 PDF2zh 的用户来说，真正困难的往往不是安装，而是：

❝

安装之后遇到各种报错，到底应该从哪里开始排查？

例如：

401 Unauthorized

429 Too Many Requests

404 Not Found

NetworkError when attempting to fetch resource

uv is not recognized

ModuleNotFoundError

Failed to canonicalize script path

甚至还有：

DLL load failed

这些错误看起来都很复杂，但实际上可以按照不同层级进行分类。

本文将围绕 Windows 环境，对 PDF2zh 最常见的问题进行系统整理。

一、先建立一个正确的故障排查思路

很多人遇到 PDF2zh 报错后，第一反应是：

重新安装

甚至直接：

删除所有环境重新安装 Python重新安装 Zotero重新安装插件

这种方法虽然有时候能够解决问题，但效率非常低。

因为 PDF2zh 实际上是多个组件共同工作的：

┌─────────────────────┐│       Zotero        ││     PDF 阅读器       │└──────────┬──────────┘           │           ▼┌─────────────────────┐│   Zotero PDF2zh      ││       插件            │└──────────┬──────────┘           │           ▼┌─────────────────────┐│    PDF2zh Server     ││   127.0.0.1:8890     │└──────────┬──────────┘           │           ▼┌─────────────────────┐│ Python / uv / conda ││    翻译运行环境       │└──────────┬──────────┘           │           ▼┌─────────────────────┐│     AI API 服务      ││ DeepSeek / OpenAI等 │└─────────────────────┘

因此：

❝

不同位置出现的错误，排查方向完全不同。

这是本文最重要的一个原则。

二、先判断：到底是哪一层出了问题？

可以把问题简单分成五类。

只要先确定属于哪一层，排查速度会快很多。

三、第一类：Zotero 无法连接 PDF2zh Server

这是最常见的一类问题。

例如 Zotero 中提示：

NetworkError when attempting to fetch resource

或者：

Connection refused

或者点击：

检查连接

之后显示：

连接失败

四、解决 NetworkError 的第一步：确认 Server 是否启动

进入 PDF2zh Server 目录。

例如：

cd /d D:\ZoteroExt\zotero-pdf2zh\server

然后：

python server.py

正常情况下应该启动：

http://127.0.0.1:8890

PDF2zh 当前官方安装文档默认 Server 地址就是：

http://127.0.0.1:8890

并且默认只监听本机。

因此：

❝

如果 server.py 没有运行，Zotero 插件自然无法连接。

五、第二步：检查 Zotero 中的 Server 地址

进入：

Zotero ↓工具 ↓PDF2zh 首选项

找到：

Python Server IP

默认应该是：

http://127.0.0.1:8890

如果 Server 使用默认端口，那么 Zotero 这里也应该使用默认端口。

六、第三步：检查 8890 端口是否被占用

如果启动 Server 时出现：

Address already in use

或者：

Port 8890 is already in use

说明：

❝

8890 已经被其他程序占用。

Windows 可以使用：

netstat -ano | findstr :8890

例如：

TCP    127.0.0.1:8890    0.0.0.0:0    LISTENING    12345

最后的：

12345

就是 PID。

可以进一步执行：

tasklist | findstr 12345

查看到底是哪一个程序占用了端口。

七、端口冲突怎么解决？

最简单的方法是换一个端口。

例如使用：

python server.py --port=9999

然后 Zotero 插件中的：

Python Server IP

同步改成：

http://127.0.0.1:9999

注意：

❝

两个地方必须同时修改。

官方 FAQ 也明确给出了这种端口切换方式。

八、第二类：401 Unauthorized

如果翻译时出现：

HTTP 401

或者：

401 Unauthorized

这类问题通常与：

❝

API 身份认证

有关。

最常见的原因就是：

API Key 错误

九、401 的排查顺序

建议按照以下顺序检查：

① API Key      ↓② API Endpoint      ↓③ 模型名称      ↓④ API账户状态

1. 检查 API Key

确认：

API Key

是否复制正确。

尤其注意：

前后空格

以及：

引号

不要把：

"sk-xxxxxxxx"

连同引号一起复制进去。

十、检查 API Key 是否已经失效

有些 API Key 可能因为：

• 主动删除；
• 账户安全策略；
• 服务商策略；
• Key 到期；

导致失效。

这种情况下，即使 PDF2zh：

Python

完全正常，

Server

也完全正常，

仍然会返回：

401

所以不要因为出现 401 就重新安装 Python。

十一、第三方 API 的 401

如果使用的是 OpenAI-compatible API：

PDF2zh ↓兼容接口 ↓第三方服务

那么还需要检查：

❝

API Key 是否属于当前这个服务。

例如：

服务A的 Key

不能直接拿去访问：

服务B的 API

即使两个服务都声称兼容 OpenAI API。

十二、第三类：404 Not Found

如果出现：

HTTP 404

通常优先检查：

API Base URL

例如某个服务要求：

https://example.com/v1

而你配置成：

https://example.com

最终请求路径可能就不正确。

十三、为什么“兼容 OpenAI API”仍然可能出现 404？

因为：

❝

“兼容 OpenAI API”并不一定代表所有接口、参数和路径都完全一致。

可能存在：

/chat/completions

支持，

但是：

/embeddings

不支持。

也可能 API 服务要求：

/v1/chat/completions

而你配置的 Base URL 已经包含：

/v1

如果再次拼接，就可能形成错误路径。

所以出现 404 时：

❝

优先检查 API URL，而不是重新安装 PDF2zh。

十四、第四类：429 Too Many Requests

这是 AI API 使用过程中非常常见的错误。

例如：

HTTP 429

或者：

Too Many Requests

也可能出现：

insufficient_quota

这几种情况虽然都可能表现为 429，但具体原因并不完全一样。

十五、429 的常见原因

主要包括：

请求频率过高API 并发限制账户额度不足账户余额不足服务商限流

因此：

❝

429 并不等于 PDF2zh 安装失败。

如果你的论文已经开始正常翻译：

PDF解析 ↓AI请求 ↓返回部分结果 ↓429

那么 PDF2zh 本地环境实际上很可能已经正常工作。

十六、如果出现 insufficient_quota

例如：

insufficient_quota

或者：

credit_balance_exhausted

这时候应该检查：

API 服务商后台 ↓账户余额 ↓API额度 ↓模型使用权限

而不是：

重新安装 Python

十七、论文翻译为什么特别容易触发额度问题？

因为论文翻译的 Token 消耗可能非常大。

PDF2zh 项目 FAQ 给出的经验数据是：

❝

10 页英文文献通常可能消耗约 7～10 万 Token，单页约 5000 Token。

实际消耗会受到论文内容、模型、分块方式和配置影响。

所以一篇：

50页

的论文，可能产生相当可观的 Token 消耗。

这也是为什么：

❝

第一次测试不要直接拿几十页甚至上百页的论文。

十八、如何降低翻译 Token 消耗？

如果使用 pdf2zh_next 引擎，可以考虑关闭：

提取术语表

PDF2zh FAQ 提到，这样可以减少部分 Token 消耗。

当然，如果你非常重视专业术语一致性，那么关闭术语表也可能影响部分翻译体验。

因此可以根据：

成本速度术语一致性

进行取舍。

十九、第五类：uv 命令找不到

Windows 上经常看到：

'uv' 不是内部或外部命令

或者：

uv is not recognized

这种问题通常不是 PDF2zh 的问题。

而是：

❝

Windows 没有找到 uv 可执行文件。

二十、先检查 uv

打开新的 CMD：

uv --version

如果正常：

uv 0.x.x

说明已经安装。

如果仍然：

不是内部或外部命令

继续检查。

二十一、为什么安装 uv 后仍然找不到？

Windows 环境变量没有及时刷新是常见原因。

最简单的方法：

关闭当前 CMD ↓重新打开 CMD ↓uv --version

如果仍然失败，再检查 PATH。

PDF2zh 官方 FAQ 也明确提到，uv 安装后如果命令无法识别，需要检查 PATH，并重新启动终端。

二十二、Windows 下检查 PATH

可以执行：

echo %PATH%

看看是否包含 uv 的安装路径。

如果使用 PowerShell：

$env:Path

也可以检查。

二十三、临时添加 PATH

例如 uv 安装到了：

C:\Users\Username\.local\bin

PowerShell 可以临时执行：

$env:Path = "C:\Users\Username\.local\bin;$env:Path"

然后：

uv --version

官方 FAQ 也提供了 Windows PATH 的处理方式。

二十四、第六类：Python 版本不兼容

PDF2zh 当前安装文档推荐：

Python 3.12

FAQ 也明确指出项目要求 Python 3.12.0，其他版本可能产生兼容性问题。

先检查：

python --version

如果得到：

Python 3.10.x

或者：

Python 3.11.x

不要直接认为：

❝

“一定不能运行。”

但如果出现依赖安装失败、运行时异常等问题，首先应该把 Python 版本纳入排查范围。

二十五、Windows 上多个 Python 是一个大坑

例如：

Python 3.10Python 3.11Python 3.12Python 3.13

同时存在。

然后：

python --version

显示：

Python 3.10

但：

where python

可能发现多个路径。

例如：

C:\Python310\python.exeC:\Users\xxx\AppData\Local\Programs\Python\Python312\python.exe

这时候你以为自己使用的是 Python 3.12：

实际上运行的是 Python 3.10。

因此排查 Python 问题时：

❝

不要只看 python --version，同时使用 where python。

二十六、第七类：ModuleNotFoundError

例如：

ModuleNotFoundError: No module named 'xxx'

这是 Python 环境中非常典型的错误。

很多人的第一反应是：

pip install xxx

但对于新版 PDF2zh：

❝

不建议一看到缺包就直接使用系统 pip 安装。

原因是当前版本已经将翻译环境独立管理。

官方安装文档明确说明，普通用户不需要手动安装 pdf2zh_next / BabelDOC。

二十七、正确的处理方式：先判断缺的是谁

例如：

ModuleNotFoundError

首先判断：

Server 本身缺依赖？

还是：

翻译环境缺依赖？

如果是 Server 本身，可以检查：

python -m pip install -r requirements.txt

如果是翻译环境，则优先考虑：

python update_packages.py

让 PDF2zh 自己更新对应环境。

二十八、第八类：Failed to canonicalize script path

这是 Windows 用户非常值得单独注意的一个错误。

典型表现：

Failed to canonicalize script path

或者类似：

uv trampoline failed to canonicalize script path

这个问题通常不是：

API Key

也不是：

Zotero

而是：

❝

虚拟环境中的脚本路径与当前实际目录不一致。

二十九、为什么移动文件夹会导致这个问题？

例如最初：

D:\ZoteroExt\zotero-pdf2zh\

创建了虚拟环境。

之后你把整个目录移动：

D:\ZoteroExt\

变成：

E:\Tools\

虽然：

server.py

还在。

但是虚拟环境里的某些脚本仍然可能指向旧路径。

于是执行：

pdf2zh.exe

时，就可能出现：

Failed to canonicalize script path

PDF2zh 官方 FAQ 对这一问题的解释也是虚拟环境路径与创建时路径不一致。

三十、解决 Failed to canonicalize script path

进入：

server

目录。

找到：

zotero-pdf2zh-next-venv

或者：

zotero-pdf2zh-venv

对应的虚拟环境目录。

删除对应的环境目录。

然后重新：

python server.py

让 PDF2zh 重新创建环境。

官方 FAQ 也建议，对于这种路径不一致问题，删除对应虚拟环境后重新运行 Server。

三十一、一个非常重要的注意事项

使用 uv 创建翻译环境以后：

❝

不要随意移动 Server 文件夹，也不要随意修改文件夹名称。

如果：

D:\ZoteroExt\zotero-pdf2zh

已经正常运行。

建议就保持这个路径。

不要今天：

D:\ZoteroExt\

明天：

E:\Software\

后天：

C:\Users\xxx\Desktop\

反复移动。

否则很容易重新遇到虚拟环境路径问题。

官方 FAQ 对此也进行了特别提醒。

三十二、第九类：Windows Conda 环境找不到 Python

如果使用 Conda，还可能出现：

找不到 Python 可执行文件

或者：

健康环境被识别为损坏

这在 Windows Conda 用户中尤其值得注意。

当前 PDF2zh v4.1.1 已经修正了相关路径判断问题。

Conda 环境中的 Python 位于：

<env>\python.exe

而 uv / venv 通常位于：

<env>\Scripts\python.exe

两者不能混为一谈。

三十三、如果使用 Conda 怎么处理？

如果你已经使用 Conda，并且环境本身能够正常工作：

❝

不需要为了 PDF2zh 强制迁移到 uv。

新版默认：

env_tool=auto

会优先沿用已经存在的 uv / Conda 环境。

官方文档也明确说明，已有 Conda 用户不需要迁移到 uv。

三十四、第十类：DLL load failed

Windows 上另一个比较典型的问题：

DLL load failed

例如：

ImportError: DLL load failed while importing xxx

这种错误往往和：

Python包+本地二进制依赖+Visual C++运行库

有关。

三十五、为什么 Python 包会出现 DLL 问题？

很多 Python 包并不是纯 Python。

例如某些：

AI图像处理PDF处理机器学习科学计算

库底层包含：

.dll

动态链接库。

如果 Windows 缺少对应运行库，就可能出现：

DLL load failed

三十六、解决 Windows DLL 问题

PDF2zh FAQ 提到，可以考虑：

❝

安装 Microsoft Visual C++ Redistributable。

Windows 用户通常需要根据具体报错检查：

x64x86

版本。

如果已经安装 x64 版本仍然报错，也可能缺少 x86 运行库。

三十七、第十一类：镜像源下载失败

PDF2zh 在首次建立翻译环境时，需要下载 Python 包和相关资源。

如果网络环境不稳定，可能出现：

Connection timeout

或者：

Failed to download

三十八、为什么国内用户尤其容易遇到这个问题？

因为安装过程中可能涉及：

PyPIPython Package模型资源字体资源其他依赖

如果某个下载源连接不稳定，就可能造成：

安装速度慢下载超时安装失败

三十九、镜像源怎么排查？

当前 PDF2zh 文档提供了镜像相关配置。

例如可以尝试：

python server.py --enable_mirror=False

或者切换到其他镜像源。

例如：

清华阿里云

具体配置应以当前版本文档为准。

四十、第十二类：第一次翻译一直卡着不动

如果第一次执行翻译：

Processing...

长时间没有明显变化。

不要立刻判断：

❝

软件死机。

因为第一次运行可能正在进行：

创建环境 ↓下载 Python ↓安装 pdf2zh_next ↓安装 BabelDOC ↓下载资源 ↓验证环境

官方安装文档明确说明，首次真正执行 pdf2zh_next 时，Server 会自动选择环境管理器、创建环境、安装兼容版本及依赖，并进行能力检查。

四十一、如何判断是真的卡住还是正在安装？

观察：

CMD / PowerShell

窗口。

如果持续出现：

DownloadingInstallingResolvingPreparingChecking

说明程序可能仍在工作。

如果：

十几分钟完全没有任何输出

并且：

CPU网络磁盘

都没有明显活动，则可以进一步检查。

四十二、可以尝试手动更新翻译环境

进入：

server

目录。

执行：

python update_packages.py

官方文档将这个脚本作为翻译环境更新/修复的重要入口。

四十三、第十三类：插件安装以后没有菜单

如果 XPI 已经安装，但是 Zotero 中：

没有 PDF2zh

优先检查：

Zotero版本+插件版本

当前项目文档支持 Zotero：

78910

并建议从最新 Release 获取插件，而不是使用很旧的版本。

四十四、不要混用老版本教程

这是目前 PDF2zh 用户特别容易踩的坑。

网络上仍然可以看到大量旧教程：

v2.xv3.x

甚至更早版本的：

server.zip

安装方式。

但是当前项目已经采用新的架构。

官方安装文档明确指出：

❝

从 v4.1.0 开始，Server、Zotero 插件和 Python 翻译环境分别维护。

所以：

❝

不要把旧教程中的命令和新版 Server 混在一起执行。

四十五、第十四类：为什么不建议手动安装 BabelDOC？

这是新版 PDF2zh 与旧教程最大的区别之一。

很多旧教程会告诉你：

pip install BabelDOC

或者：

pip install pdf2zh_next

但对于普通用户来说，新版 Server 会自动管理这些依赖。

官方安装文档明确表示：

❝

普通用户不需要手工决定 pdf2zh_next、BabelDOC、PyMuPDF 的具体版本。

所以：

❌ 手动安装一堆依赖

不如：

✅ python server.py

让 Server 管理翻译环境。

四十六、第十五类：终端出现大量红色文字，是不是一定失败？

不一定。

Python 程序中：

WARNING

和：

ERROR

的含义并不完全相同。

尤其是：

WARNING

不一定会导致任务失败。

判断是否真正失败，应该重点看：

最终异常

以及：

翻译任务是否完成

四十七、排查问题时不要只截图 Zotero

这是非常重要的一点。

如果你需要让别人帮助排查 PDF2zh：

❝

最有价值的信息往往不是 Zotero 弹窗，而是 Server 终端中的完整日志。

例如：

CMD窗口

中出现：

Traceback...Error...

这些信息比：

Zotero：翻译失败

有价值得多。

PDF2zh 官方 FAQ 也建议提交问题时提供：

终端完整内容Zotero设置截图Zotero弹窗截图

以便定位问题。

四十八、一个非常实用的故障定位方法

假设 Zotero 出现：

NetworkError

不要马上认为：

网络有问题

而是按照下面的方法：

Zotero ↓检查连接 ↓如果失败 ↓检查 server.py ↓检查 8890 ↓检查防火墙 ↓检查插件版本

如果：

检查连接正常

但是：

翻译失败

那么：

Zotero ↔ Server

已经基本正常。

接下来应该检查：

Python环境 ↓翻译引擎 ↓AI API

四十九、建议建立一套“从外到内”的排查顺序

可以把整个系统想象成五层：

第一层：Zotero        ↓第二层：PDF2zh 插件        ↓第三层：Server        ↓第四层：Python / uv / conda        ↓第五层：AI API

出现问题以后：

❝

从外向内排查。

例如：

① Zotero能否看到插件？        ↓② 插件能否连接Server？        ↓③ Server能否正常启动？        ↓④ Python环境是否正常？        ↓⑤ AI API是否正常？

这样比“全部重装”效率高得多。

五十、一个完整的故障排查表

最后可以把常见错误整理成一张表。

五十一、遇到问题时，建议按照这个流程操作

以后再遇到 PDF2zh 报错，可以直接按照：

Step 1确认 Zotero 版本       ↓Step 2确认 PDF2zh 插件版本       ↓Step 3确认 server.py 是否运行       ↓Step 4确认 127.0.0.1:8890       ↓Step 5点击“检查连接”       ↓Step 6查看 Server 终端日志       ↓Step 7确认 Python / uv / conda       ↓Step 8确认翻译环境       ↓Step 9确认 API Key       ↓Step 10确认 API额度/限流

这样基本可以覆盖绝大多数常见问题。

五十二、最后：不要轻易“全部重装”

这是我最想提醒 Windows 用户的一点。

当 PDF2zh 出问题时：

❌ 删除 Zotero❌ 删除 Python❌ 删除所有插件❌ 重装系统

通常都不是第一选择。

更合理的方法是：

找到错误   ↓确定错误所在层级   ↓针对性处理   ↓重新测试

例如：

401

就检查：

API Key

而不是：

Python

又比如：

Failed to canonicalize script path

就检查：

虚拟环境路径

而不是：

DeepSeek API

再比如：

429

就检查：

API额度 / 限流

而不是：

重新安装 Zotero

五十三、总结

PDF2zh 的完整运行链路可以归纳成：

Zotero ↓PDF2zh插件 ↓PDF2zh Server ↓Python / uv / conda ↓pdf2zh_next ↓AI API ↓翻译结果 ↓双语PDF

所以，所谓的“PDF2zh 报错”，实际上可能发生在完全不同的环节。

真正高效的排查方法不是：

❝

看到错误 → 全部重装。

而是：

❝

看到错误 → 定位层级 → 分析原因 → 针对性修复。

对于 Windows 用户来说，只要掌握下面这几类错误的判断方法：

401 → API认证404 → API地址429 → 限流/额度NetworkError → Server/网络uv → PATH/环境Python → 版本/路径ModuleNotFoundError → 依赖环境Failed to canonicalize → 虚拟环境路径DLL → Windows运行库/二进制依赖

基本就已经掌握了 PDF2zh 日常维护的大部分核心思路。

而如果你准备长期使用 Zotero + PDF2zh，建议不要只关注“翻译能不能成功”，还应该逐渐建立自己的：

Python 环境管理 + PDF2zh Server + Zotero 插件 + AI API + 故障排查

体系。

这样以后无论是更换 AI 模型、升级 Zotero、升级 PDF2zh，还是更换电脑，都能够比较快速地恢复整个科研文献翻译环境。

官方资料

PDF2zh 当前官方项目及文档建议优先参考：

• PDF2zh 官方 GitHub 项目：Zotero PDF2zh 官方项目
• 当前安装指南：PDF2zh 安装指南
• 环境问题 FAQ：PDF2zh 环境问题 FAQ
• 虚拟环境 FAQ：PDF2zh 虚拟环境 FAQ

建议实际操作时，以当前 Release 对应的官方文档为准，因为 PDF2zh 的 Server、插件和 Python 翻译环境仍在持续更新。

❝

本公众号发布的内容除特别标明外版权归原作者所有。若涉及版权问题，请联系我们。所有信息及评论区内容仅供参考，请读者自行判断信息真伪，不构成任何投资建议。据此产生的任何损失，本公众号概不负责，亦不负任何法律责任。