跳到主要内容
PPDF123

pdfx：PDF123 命令行工具

pdfx 是 PDF123 的命令行工具，在 npm 上以 @pdf123/cli 发布。它可以对磁盘上的文件运行合并、拆分、压缩、OCR 等 95 个 PDF 工具：把文件发送到 PDF123 API 或你自己的服务器，再把结果保存到本地。

@pdf123/cliNode 20.3 或更高版本，或 Bun

安装

npm install -g @pdf123/cli
本页内容

如何安装 pdfx？

全局安装该包即可获得 pdfx 命令。也可以不安装，直接运行一次。

Installbash
npm install -g @pdf123/cli
pdfx --version
Run without installingbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf
bunx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

bun add -g @pdf123/cli 和 pnpm add -g @pdf123/cli 同样可用。不需要再安装其他任何东西。

如何快速上手？

下面六条命令展示了常见用法。

Quick startbash
pdfx list                                          # every tool; --category security for one category
pdfx describe watermark                            # a tool's fields and defaults
pdfx merge a.pdf b.pdf -o merged.pdf
pdfx compress *.pdf -o compressed/                 # several files: one result per file
pdfx watermark in.pdf --watermarkText DRAFT
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf

如何运行任意工具？

第一个参数是工具 id，后面依次是输入文件和该工具的选项。工具的每个选项都是一个标志，写作 API 字段名（--pageNumbers）或短横线形式（--page-numbers）。负数可以用空格接在标志后面，如 --rotation -90，也可以接在等号之后。

Syntaxtext
pdfx <tool> [files...] [--<field> <value>]...

用 pdfx list 查看工具。它支持 --category 或 --group，以及带搜索词的 --query。用 pdfx describe <tool> 查看端点、接受的输入、该工具是否以批量方式运行，以及每个字段的默认值和允许取值。工具 id 未知时会给出建议，拼写错误则以退出码 2 退出。

哪些命令对应哪些工具页面？

命令工具页面功能
pdfx merge a.pdf b.pdf -o merged.pdf合并将多个 PDF 合并为一个
pdfx split report.pdf --pageNumbers 3,7 -o parts.zip拆分将一个 PDF 拆分为多个文件
pdfx compress in.pdf -o out/压缩重新压缩 PDF 数据流以减小体积
pdfx watermark in.pdf --watermarkText DRAFT水印添加文字或图片水印
pdfx protect in.pdf --password secret -o locked.pdf加密保护用密码加密 PDF
pdfx unlock locked.pdf --password secret解锁移除密码保护
pdfx get-info in.pdf文档信息以 JSON 输出元数据、权限和结构
pdfx ocr scan.pdf -o out/OCR识别扫描版 PDF 并保存为 Markdown
pdfx pdf-to-markdown in.pdf -o out/PDF 转 Markdown将 PDF 转换为 Markdown
pdfx rotate in.pdf --angle 90旋转将页面方向旋转 90、180 或 270 度
pdfx repair broken.pdf修复重建损坏 PDF 的结构

如何一次处理多个文件？

给单文件工具传入多个文件，pdfx 就会以批量方式运行。请用 -o 指定以斜杠结尾的目录。工具对每个文件各运行一次，默认同时处理两个文件，可用 --concurrency 修改。

Batchbash
pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

每个文件处理完成时，pdfx 会输出一行 input -> saved。失败的文件会报告到标准错误输出，其他文件仍会处理完。按一次 Ctrl-C 会中止正在进行的请求，已保存的文件会保留。再按一次 Ctrl-C 会立即退出，退出码为 130。使用 --idempotency-key k 时，每个文件发送 k:<index>，24 小时内重复同一请求会重放第一次的结果。

对返回报告的工具（例如 get-info）进行批量处理时，不带 -o 不会写入任何文件，而是按输入文件输出各自的报告。

如何在一次请求中串联多个工具？

pdfx pipeline 在一次请求中运行多个工具。每个工具重复一次 --step。如需设置选项，请用 --steps 传入 JSON 数组。

Pipelinesbash
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf
pdfx pipeline in.pdf --steps '[{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' -o out.pdf

步骤中不能使用需要第二个文件的工具。

如何打开有密码的 PDF？

--input-password 会先打开所有加密的输入。--password-for <file>=<password> 为单个文件设置密码，可以重复使用，文件名写成 * 则涵盖其余所有文件。这适合同时包含加密文件和未加密文件的批量任务。对于 merge 和 images-to-pdf，每个指定的文件会在工具运行前分别解锁。

Passwordsbash
pdfx compress locked.pdf --input-password secret -o out.pdf
pdfx compress report.pdf --password-for report.pdf=secret -o out.pdf
pdfx merge a.pdf b.pdf --password-for a.pdf=secret -o merged.pdf

流水线中同样可以使用这些选项。若要永久移除保护，请使用解锁工具及其自己的 --password 选项。

输入和输出如何工作？

  • 输入为 - 时读取标准输入，每次运行只能使用一次。-o - 把结果写到标准输出。
  • -o file.pdf 写入该文件，-o dir/ 写入目录。尚不存在的目录需要加结尾斜杠，因为不带斜杠的名称会被当作文件来写入。
  • 不带 -o 时，结果以服务器给出的文件名写入当前目录。
  • 写入目录时，pdfx 从不替换已有文件，而是另取一个新名称。明确指定 -o file.pdf 则会替换该文件。
  • 如果 -o 的文件名扩展名与结果相矛盾，例如把 split 产生的 ZIP 保存为 .pdf，会以退出码 2 和 code: output_mismatch 拒绝，且不写入任何内容。
  • 无法写入的输出属于用法错误，会在上传任何内容之前发现。
Shell pipebash
cat in.pdf | pdfx compress - -o - > out.pdf

--json 会输出什么？

对于已保存的结果，--json 输出路径、内容类型和大小。返回报告的工具则输出报告本身。批量处理输出一份报告，其中包含每个文件的状态。

Single resultjson
{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }
Batch reportjson
{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

失败的文件用 error 和 reason 代替 path 和 bytes。没有匹配的过滤类工具输出 { "matched": false }。pdfx list --json 输出的每一行包含 id、category、group、name、description、returns、files 和 filter。

哪些选项对所有工具都适用？

选项作用
-o, --output <path>要写入的文件，或要写入的目录。默认是当前目录。- 表示标准输出
--api-base <url>API 源地址。环境变量为 PDFX_API_BASE，默认值为 https://pdf123.xyz
--api-key <key>以 X-API-KEY 发送。环境变量为 PDFX_API_KEY。可选
--input-password <pw>先打开所有受密码保护的输入
--password-for <file>=<pw>单个文件的密码。可重复使用
--concurrency <n>批量处理时同时处理的文件数。默认为 2
--timeout <ms>每个请求的超时时间。默认为 300000
--idempotency-key <k>24 小时内重放第一次的结果
--json机器可读的输出

退出码有哪些？

退出码含义
0成功。没有匹配的过滤类工具同样以 0 退出，并输出 no match
1请求失败。批量处理中至少有一个文件失败，其他文件仍会处理完
2用法错误。未上传任何内容
130被 Ctrl-C 中断。正在进行的请求被中止

失败时，如果服务器提供了相应信息，会输出 reason:、code: 和 hint: 行，这样脚本无需匹配文本就能分支处理。如果工具没有可返回的内容，例如对没有表格的 PDF 运行 pdf-to-csv，会以退出码 1 和 code: no_content 退出，而不是写入空文件。这些错误码列在错误码页面。

如何让 pdfx 指向自己的服务器？

把 PDFX_API_BASE（或 --api-base）设置为自托管 pdfx-server 的地址。如果你的服务器需要密钥，再加上 PDFX_API_KEY。参见自托管。

Self-hosted serverbash
export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

如何运行 CLI 不认识的端点？

pdfx call 向操作 id 或 /api/... 路径发送原始请求。用 --field name=value 传递表单字段，用 --file field=path 传递额外的文件。它只发送一次请求，也不在本地做任何校验，因此密码和批量处理会被拒绝。

Raw requestsbash
pdfx call general/merge-pdfs a.pdf b.pdf -o merged.pdf
pdfx call /api/v1/misc/flatten in.pdf --field flattenOnlyForms=true -o flat.pdf

常见问题

pdfx 可以离线使用吗？

不可以。pdfx 会把每个文件上传到 PDF123 API 或你自己的服务器，再把结果保存到本地，因此 API 基础地址必须可以访问。

pdfx 需要 API 密钥吗？

不需要。可以匿名使用。如果你的服务器要求密钥，请设置 PDFX_API_KEY 或传入 --api-key。密钥以 X-API-KEY 请求头发送。

pdfx 需要哪个版本的 Node？

Node 20.3 或更高版本，或 Bun。

pdfx 会覆盖我的文件吗？

写入目录时不会：已有文件从不会被替换。如果你用 -o file.pdf 自己指定输出文件名，该文件会被替换，因此想保留原文件时请选用新的名称。

过滤类工具没有匹配时会怎样？

过滤类工具（id 以 filter- 开头）在条件成立时会让文件通过。条件不成立时，pdfx 输出 no match 并以退出码 0 退出。在批量处理中，这样的文件算作未匹配，而不是失败。