你希望我基于这份 Zotero-pdf2zh 插件部署教程，对内容进行补充和丰富，让教程更易懂、更全面，能更好地帮助新手完成 PDF 翻译服务的部署和使用。

我会从新手友好性、实操细节、问题兜底、优化建议四个维度对教程进行丰富，保留核心逻辑的同时，补充更多实用信息：

【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式（增强版）

引言

在学术研究中，阅读外文文献是常态，而一款能在翻译时保留原文格式（尤其是公式、图表、双栏排版）的工具则至关重要。PDFMathTranslate Next 借助 BabelDOC 翻译引擎，能轻松实现“结构保持 + 双语对照”的精准翻译，解决了传统翻译工具“格式乱码、公式丢失”的痛点，是处理科研文献的理想选择。

目前，Zotero + PDF2zh/PDF2zh_next 的组合已成为科研人翻译外文文献的主流方案，Zotero-pdf2zh 插件更新至 3.x 版本后，操作更简洁、兼容性更强。本教程将保姆级引导你完成配置，并详细演示 Python 和 Docker 两种部署方式（附避坑指南），即使是零基础也能快速上手。

补充说明：

项目资源（整理版）

资源名称 链接 备注
Zotero-pdf2zh 插件 guaguastandup/zotero-pdf2zh 下载 v3.x.x 版本 .xpi 文件
PDF2zh_next 核心项目 PDFMathTranslate-next 翻译引擎核心
插件网盘备份（国内） https://pan.quark.cn/s/4242e66baf05?pwd=79Xd 解决 GitHub 下载慢问题

环境依赖（补充版）

必装组件

  1. Python 3.12
  2. Zotero 7 桌面端
    • 下载：Zotero 官网（Zotero 8 暂未适配插件，暂不推荐）
    • 插件安装：下载 .xpi 文件后，打开 Zotero → 工具 → 插件 → 拖入 .xpi 文件 → 重启 Zotero（若未生效，重启电脑重试）
  3. 模型服务（OpenAI 兼容）
    • 需准备：API Key + Base URL + 模型名（新手推荐先试用「硅基流动免费通道」，无需自己申请 Key，配置见下文）

可选组件

Part 1：Python 部署（新手友好版）

前置准备：检查网络与命令行

  1. 打开终端/CMD/PowerShell，执行以下命令验证 Python 安装：
    1
    2
    python --version  # 应输出 Python 3.12.x
    # 若报错，尝试 python3 --version 或 py -3 --version（Windows）
  2. 国内用户建议先配置 pip 镜像（永久生效，避免依赖下载失败）：
    1
    2
    3
    4
    5
    6
    7
    8
    # Windows（PowerShell）
    mkdir $env:USERPROFILE\.pip
    New-Item $env:USERPROFILE\.pip\pip.ini -Force
    Add-Content $env:USERPROFILE\.pip\pip.ini "[global]`nindex-url = https://mirrors.ustc.edu.cn/pypi/simple/`ntrusted-host = mirrors.ustc.edu.cn"

    # macOS/Linux（终端）
    mkdir -p ~/.pip
    echo -e "[global]\nindex-url = https://mirrors.ustc.edu.cn/pypi/simple/\ntrusted-host = mirrors.ustc.edu.cn" > ~/.pip/pip.conf

第一步：安装 uv（简化虚拟环境管理）

系统 安装命令（推荐官方脚本） 备用命令（pip 安装）
Windows powershell -ExecutionPolicy ByPass -c “irm https://astral.sh/uv/install.ps1 iex”
macOS/Linux curl -LsSf https://astral.sh/uv/install.sh sh 或 wget -qO- https://astral.sh/uv/install.sh

关键：验证 uv 安装并配置 PATH

1
2
3
4
5
6
7
8
# 检查 uv 版本（必做）
uv --version

# 若报错“uv 不是内部命令”，执行以下命令（临时生效，重启终端后需重新执行，或手动添加到系统环境变量）
# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
# macOS/Linux
export PATH="$HOME/.local/bin:$PATH"

第二步：下载并解压项目文件

Windows（CMD/PowerShell）

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建并进入文件夹（建议放在非中文路径，如 D:\zotero-pdf2zh）
mkdir D:\zotero-pdf2zh && cd D:\zotero-pdf2zh

# 2. 下载 server.zip（国内备用链接：https://pan.quark.cn/s/4242e66baf05?pwd=79Xd 提取 server.zip）
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip

# 3. 解压（PowerShell 命令，兼容所有 Windows 版本）
powershell -Command "Expand-Archive -Path '.\server.zip' -DestinationPath '.' -Force"

# 4. 进入 server 目录
cd server

macOS/Linux

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建并进入文件夹
mkdir -p ~/zotero-pdf2zh && cd ~/zotero-pdf2zh

# 2. 下载 server.zip
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip

# 3. 解压
unzip server.zip

# 4. 进入 server 目录
cd server

解压后目录结构（核对）

1
2
3
4
5
6
7
server/
├── server.py          # 核心启动文件
├── requirements.txt   # 依赖清单
├── config/            # 配置文件夹（自动生成）
├── translated/        # 翻译结果输出文件夹
├── doc/               # 文档说明
└── utils/             # 工具函数

第三步：安装依赖并启动服务（分3种场景）

场景1：网络正常 → 直接启动（新手首选）

1
2
# 进入 server 目录后执行
python server.py

首次启动说明：

  • 第一次执行会自动安装依赖（约1-3分钟，视网络而定），安装完成后终端会自动退出；
  • 第二次执行 python server.py 才会真正启动服务，成功后终端会显示：
    1
    2
    * Running on http://127.0.0.1:8890
    * Serving Flask app 'server'

场景2：网络波动 → 预热依赖（避免安装失败）

1
2
3
4
5
6
7
8
9
10
11
12
13
# Windows
.\install-with-uv.bat --warmup  # 用 uv 预热（推荐）
# 或
.\install-with-conda.bat --warmup  # 用 conda 预热（需先装 Anaconda/Miniconda）

# macOS/Linux
./install-with-uv.sh --warmup
# 或
./install-with-conda.sh --warmup

# 预热完成后，启动服务
python server.py --skip_install=True  # 首次启动
python server.py  # 后续启动（无需 skip_install）

场景3：手动安装依赖（兜底方案）

若自动安装失败，手动创建虚拟环境并安装依赖：

1
2
3
4
5
6
7
8
9
10
11
# 1. 创建虚拟环境（uv 版）
uv venv zotero-pdf2zh-venv --python 3.12

# 2. 激活虚拟环境
# Windows
.\zotero-pdf2zh-venv\Scripts\Activate.ps1
# macOS/Linux
source ./zotero-pdf2zh-venv/bin/activate

# 3. 安装依赖
pip install pdf2zh_next pypdf PyMuPDF flask toml

常用启动参数（按需调整）

参数 作用 示例
–port=8891 切换端口（避免 8890 被占用） python server.py –port=8891
–enable_venv=False 关闭虚拟环境管理 python server.py –enable_venv=False
–enable_winexe=True 使用 Windows 版 exe 作为翻译引擎 python server.py –enable_winexe=True –winexe_path=”D:\pdf2zh\pdf2zh.exe”

第四步：一键启动脚本（优化版）

手动每次输命令太麻烦？制作一键启动脚本，双击即可启动服务：

Windows（.bat 脚本）

  1. 新建文本文档，粘贴以下内容（替换 PROJECT_PATH 为你的 server 目录）：
    1
    2
    3
    4
    5
    6
    7
    @echo off
    chcp 65001 >nul  # 解决中文乱码
    set PYTHONUTF8=1
    set "PROJECT_PATH=D:\zotero-pdf2zh\server"  # 替换为你的实际路径
    cd /d "%PROJECT_PATH%"
    python server.py --port=8890
    pause  # 防止服务启动后终端关闭
  2. 保存为 启动翻译服务.bat（保存类型选“所有文件”，后缀为 .bat）；
  3. 双击该文件即可启动服务。

macOS/Linux（.sh 脚本）

  1. 新建文本文件，粘贴以下内容：
    1
    2
    3
    4
    5
    6
    7
    #!/usr/bin/env bash
    set -euo pipefail
    export PYTHONUTF8=1
    PROJECT_PATH="$HOME/zotero-pdf2zh/server"  # 替换为你的实际路径
    cd "$PROJECT_PATH"
    python3 server.py --port=8890
    read -rp "服务已启动，按 Enter 退出..." _
  2. 保存为 start_service.sh，并赋予执行权限：
    1
    chmod +x start_service.sh
  3. 双击或终端执行 ./start_service.sh 启动服务。

Part 2：Docker 部署（免环境配置，推荐新手）

Docker 部署的核心优势：无需配置 Python/uv/依赖，一键启动，跨系统兼容。

第一步：验证 Docker 环境

1
2
docker --version       # 检查 Docker 是否安装
docker compose version # 检查 Compose 版本（老版本用 docker-compose --version）

若 Docker Desktop 启动失败（Windows）：需开启 WSL2，参考 WSL2 安装指南

第二步：下载 Docker 配置文件

1
2
3
4
5
6
7
8
9
10
11
# Windows（CMD）
mkdir D:\zotero-pdf2zh_docker && cd D:\zotero-pdf2zh_docker
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip
powershell -Command "Expand-Archive -Path '.\docker.zip' -DestinationPath '.' -Force"
cd docker

# macOS/Linux
mkdir -p ~/zotero-pdf2zh_docker && cd ~/zotero-pdf2zh_docker
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip
unzip docker.zip
cd docker

第三步：加速镜像下载（国内用户必做）

  1. 打开 Docker Desktop → 设置 → Docker Engine；
  2. 粘贴以下配置（添加国内镜像源），保存并重启 Docker：
    1
    2
    3
    4
    5
    6
    {
      "registry-mirrors": [
        "https://docker.mirrors.ustc.edu.cn",
        "https://hub-mirror.c.163.com"
      ]
    }

第四步：预拉取核心镜像（避免启动超时）

1
docker pull awwaawwa/pdfmathtranslate-next:latest  # 核心翻译镜像

第五步：启动 Docker 服务

1
2
# 进入 docker 目录后执行
docker compose up -d --build
  • 启动成功：执行 docker logs -f zotero-pdf2zh 可查看日志，显示 Running on http://127.0.0.1:8890 即成功；
  • 常用管理命令：
    1
    2
    3
    docker stop zotero-pdf2zh    # 停止服务
    docker start zotero-pdf2zh   # 启动服务
    docker compose down          # 停止并删除容器

可选：切换为 pdf2zh 1.x 版本

若需使用旧版 pdf2zh（1.x），修改 docker-compose.yaml 和 Dockerfile 中的镜像地址：

1
2
# docker-compose.yaml 中修改
ZOTERO_PDF2ZH_FROM_IMAGE: byaidu/pdf2zh:1.9.6
1
2
# Dockerfile 中修改
ZOTERO_PDF2ZH_FROM_IMAGE=byaidu/pdf2zh:1.9.6

修改后重新构建：

1
2
docker compose down
docker compose up -d --build

Part 3：Zotero 插件配置与使用（核心步骤）

无论用 Python 还是 Docker 部署，最终都需在 Zotero 中配置插件：

第一步：插件基础配置

  1. 打开 Zotero → 编辑 → 首选项 → PDF2zh；
  2. 核心配置项（新手推荐默认值）：
    配置项 推荐值（新手） 说明
    服务地址 http://127.0.0.1:8890 与部署的服务端口一致
    翻译引擎 pdf2zh_next Docker/Python 部署默认用此引擎
    Base URL https://api.siliconflow.cn/v1 硅基流动免费通道（无需 API Key）
    模型名 THUDM/GLM-4-9B-0414 硅基流动免费模型
    API Key 留空 硅基流动免费通道无需填写
    QPS/并发数 1/1 免费模型建议低并发，避免触发限流

第二步：开始翻译（4种常用功能）

  1. 翻译PDF：选中文献 → 右键 → 翻译PDF → 生成双语/单语译文（格式与原文一致）；
  2. 裁剪PDF：自动裁剪空白，适合小屏阅读（双栏论文必备）；
  3. 双语对照：生成“左原右译”PDF，方便对照阅读；
  4. 双语对照（裁剪）：先裁双栏为单栏，再左右拼接（适配多数英文期刊论文）。

新手福利：免费模型推荐（无需自己申请 API Key）

模型服务商 Base URL 模型名 优势
硅基流动 https://api.siliconflow.cn/v1 THUDM/GLM-4-9B-0414 免费、无需注册、稳定
火山引擎 https://maas-api.volcengine.com/api/v1 volc-unicorn-pro 每日免费额度高（需注册）

Part 4：常见问题解答（FAQ 增强版）

Q1：服务启动失败，提示“端口 8890 被占用”？

解决：

  1. 查看占用端口的程序：
    1
    2
    3
    4
    # Windows
    netstat -ano | findstr :8890
    # macOS/Linux
    lsof -i :8890
  2. 要么关闭占用程序，要么启动服务时换端口：python server.py --port=8891（同时在 Zotero 插件中把服务地址改为 http://127.0.0.1:8891）。

Q2：翻译时进度条卡住，终端提示“API 请求失败”？

排查步骤：

  1. 检查 Base URL 和模型名是否填写正确（复制粘贴，避免手输错误）；
  2. 免费模型限流：降低 QPS/并发数（改为 1/1），等待 1-2 分钟重试；
  3. 网络问题：确保能访问配置的 Base URL（浏览器打开 Base URL 测试）。

Q3：Windows 启动 Python 服务时提示“缺少 DLL 文件”？

解决：安装 Microsoft Visual C++ 2015-2022 运行库（x64 版本）。

Q4：Docker 启动后，Zotero 无法连接服务？

解决：

  1. 检查 Docker 容器是否运行：docker ps（应显示 zotero-pdf2zh 容器）；
  2. 关闭电脑防火墙/杀毒软件（临时），测试是否能访问 http://127.0.0.1:8890；
  3. Docker 端口映射问题：检查 docker-compose.yaml 中 ports: - "8890:8890" 是否配置。

Q5：翻译后的 PDF 公式乱码/字体缺失？

解决：

  1. 下载开源字体（如「霞鹜文楷」），放到 server/config 目录；
  2. Docker 部署：在 docker-compose.yaml 中挂载字体文件：
    1
    2
    volumes:
      - ./LXGWWenKai-Regular.ttf:/app/LXGWWenKai-Regular.ttf:ro

Q6：实在搞不定部署怎么办？

兜底方案：

  1. 使用 沉浸式翻译 → 常用功能 → Babeldoc → 登录后拖入 PDF 翻译；
  2. 加入 QQ 群（971960014，验证：github），提供「终端日志 + Zotero 配置截图」，群友/作者会协助解决。

进阶优化建议

  1. 持久化配置：将 API Key、Base URL 写入 server/config/config.toml，避免每次重启服务重新配置；
  2. 批量翻译：在 Zotero 中选中多篇文献，右键 → 翻译PDF，支持批量处理；
  3. 自定义输出路径：修改 server/utils/config.py 中的 config.translated_path，指定翻译结果保存路径；
  4. 更新插件/服务：
    • 插件：Zotero → 工具 → 插件 → 检查更新；
    • Python 服务：进入 server 目录，执行 git pull（需先装 Git）后重启；
    • Docker 服务：docker compose pull && docker compose up -d --build。

总结

  1. 部署选择：新手优先选 Docker 部署（免环境配置），有 Python 基础可选 Python 部署（灵活度更高）；
  2. 核心配置：服务地址需与部署端口一致，免费模型优先选「硅基流动」（无需 API Key）；
  3. 问题排查：启动失败先查端口/网络，翻译失败先查 Base URL/模型名/QPS，格式乱码补字体。

如果本教程对你有帮助，欢迎支持原作者 她笑中藏泪花 | 爱发电，也欢迎在 GitHub 给项目点 Star～