写在前面
PDF2zh 2.0 正式发布！借助 BabelDOC 引擎，排版更整洁、版面更优雅。本文将手把手演示 三种部署姿势——win exe 极速安装、本地 uv 虚拟环境，以及 Docker 容器化——并补充 Zotero-PDF2zh 插件的关键配置，助你在 Windows 11 + Python 3.12 / Docker Desktop 环境下快速上手。
运行环境示例
- Windows 11 64-bit
- Python 3.12
- Docker Desktop（建议最新稳定版）
传送门在此：
- PDF2zh 2.0 项目地址：PDF2zh 2.0
- Zotero-PDF2zh 插件仓库：Zotero-PDF2zh | Zotero PDF中文翻译插件
- BabelDOC 引擎仓库：BabelDOC
1. 翻译提示
工具概览
| 名称 | 简介 | 核心亮点 | 兼容 / 运行环境 |
|---|---|---|---|
PDF2zh 2.0 (pdfmathtranslate-next) | 独立 CLI / Web UI 的科研 PDF 翻译引擎 | 公式、图表完好保留 双语对照 / 纯译自由切换 兼容 Bing / Google / 本地或云端 LLM | Python 3.10–3.13 |
| Zotero-PDF2zh | Zotero 插件，调用本地翻译服务 | 一键翻译 + 双栏裁剪 译文自动写入 Zotero 备注 | Zotero 7 |
| uv | 轻量级打包 / 运行器 | 无需全局虚拟环境 依赖隔离彻底 | Win / macOS / Linux |
| Docker Desktop | 容器管理平台 | 一次配置，多处复用 隔离性强，易迁移 | Windows 11 (WSL2) |
兼容性提醒
- pdfminer.six 请固定到
20250416，否则公式解析可能出错。- PDF2zh 1.x 与 2.x 互不兼容：zotero插件当前仍用 1.9.6；2.0 需单独服务。
pdf文件格式
pdf翻译必须保证是可复制的文件；如果是OCR，那么请打开OCR workaround，如果不确定的话可以开启Auto enable OCR workaround。
2. 部署前准备
| 组件 | 建议版本 | 用途 |
|---|---|---|
| Windows .exe | 最新版 | 开箱即用 Web UI（无法联动 Zotero） |
| Python | 3.10–3.13 | 运行 PDF2zh 2.0 / 插件后端 |
| Zotero | 7.x | 插件已适配 |
| Docker Desktop | ≥ 4.29 | 仅路线 C 使用 |
| uv | 最新 | 仅路线 B 使用 |
| API Key（可选） | Bing 免配置；GPT / DeepSeek⋯ | 提升翻译质量 |
3 路线 A：Windows .exe 极速体验
只想用 Web GUI？
- 前往 Releases。
下载并解压
pdf2zh-<version>-with-assets-win64.zip。- 双击
pdf2zh.exe，稍等片刻自动打开浏览器；若未跳转，手动访问http://localhost:7860/。
下载贴士
- 推荐：
pdf2zh-<version>-with-assets-win64.zip（内含字体与模型）。 *-win64.zip不含资源，首次运行需在线下载，网络不佳时可能失败。
- 双击
4. 路线 B：本地虚拟环境 + Uvicorn (uv 驱动)
4.1 安装pdfzh 2.0
4.1.1 安装 uv & 创建虚拟环境
pip install uv # 安装 uv
uv venv --python 3.12 # 创建虚拟环境
.\.venv\Scripts\activate # Windows 启用4.1.2 安装 PDF2zh 2.0
uv tool install pdf2zh_next # 一键安装如果你不想手动建虚拟环境
可直接执行：
uv tool install --python 3.12 pdf2zh_next或者暴力pip install -U pdf2zh_next——只是更容易遇到依赖冲突。
如何更新？pip install -U pdf2zh_next
我这里为了演示方便，所以用Pycharm创建的虚拟环境，大家自行使用的时候可以直接不创建虚拟环境，直接输入这行代码，然后直接进行自检
4.1.3 快速自检
pdf2zh_next sample.pdf --service bing # 自检示例自检成功后，目录中会出现
sample_dual_bing.pdf（双语对照）sample_mono_bing.pdf（纯翻译）
4.1.4 启动服务
方式 1 ：Web UI
pdf2zh_next --gui # 默认监听 7860 端口如果没有自动跳转，请在浏览器手动访问 http://localhost:7860/ 打开界面。
方式 2 ：命令行翻译
pdf2zh_next "C:\Path With Spaces\document.pdf"更丰富的 CLI 用法见官方文档：高级用法
4.2 zotero-pdf2zh
插件仍基于 1.x，暂不支持 2.0，敬请关注更新。
5. 路线 C：Docker Compose 一键容器化
5.1 拉取并运行官方镜像
docker pull awwaawwa/pdfmathtranslate-next # 拉取
docker run -d --name pdf2zh -p 7860:7860 awwaawwa/pdfmathtranslate-next # 运行如访问受限，可改用 GitHub Container Registry：
docker pull ghcr.io/pdfmathtranslate/pdfmathtranslate-next # 拉取
docker run -d --name pdf2zh -p 7860:7860 ghcr.io/pdfmathtranslate/pdfmathtranslate-next # 运行启动后同样通过浏览器访问 http://localhost:7860/。
6 常见问题与排障
| 场景 | 可能原因 | 解决方案 |
|---|---|---|
| PDF 复制乱码 | 部分阅读器渲染兼容差 | 换用其他阅读器或在 Zotero 打开 |
| 端口占用 | 7860 / 8888 被占 | netstat -ano 找占用进程，或指定新端口 |
| Timeout / 429 | 接口限流 | 降低并发 / 更换 API Key |
pdfminer.six 报错 | 版本漂移 | pip install pdfminer.six==20250416 |
| Zotero 连接失败 | 防火墙 / 未监听 0.0.0.0 | 放行 Python / Docker，或修改监听地址 |
| Web UI 白屏 | 容器未起 / 端口冲突 | docker logs pdf2zh 查看日志 |
| 富文本占位符错乱 | LLM 匹配错误 | 开启 Enhance compatibility；DeepSeek-V3 命中率最低 |
更多问答：
7 如何选择最适合的路线？
| 维度 | 路线 A：.exe | 路线 B：uv | 路线 C：Docker |
|---|---|---|---|
| 上手难度 | ⭐ | ⭐⭐⭐ | ⭐⭐ |
| 环境隔离 | 弱 | 中 | 强 |
| 资源占用 | 低 | 低 | 中（Docker Daemon） |
| 部署耗时 | 秒级 | 秒级 | 首次拉镜像略慢 |
| 配置弹性 | GUI 即改 | 本地文件即改 | GUI 即改 |
| 网络依赖 | 普通网络环境 | 可能需外网 | 镜像已打包 |
| Zotero 联动 | 不支持 | 支持 | 支持 |
我的建议：
- Python：路线 B，轻装上阵。
- 团队机房 / 多人共享 / 运维友好：路线 C，一劳永逸。
- 萌新：少想，Docker 一键最香。
- 纯 GUI 需求：路线 A，下载即用。
8 收工
语言不再是科研“卡脖子”难题——PDF2zh 把翻译体验从“拔牙”降至“嗑瓜子”。祝你少踩坑，多产出，Happy Researching!
