跳至主要內容
PPDF123

pdfx：PDF123 命令列工具

pdfx 是 PDF123 的命令列工具，以 @pdf123/cli 發布在 npm。它能對磁碟上的檔案執行合併、分割、壓縮與 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），也可寫成 kebab case（--page-numbers）。負數可以用空格接在旗標之後，如 --rotation -90，也可以接在等號之後。

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

用 pdfx list 查看工具。它接受 --category 或 --group，以及後面接搜尋字詞的 --query。用 pdfx describe <tool> 可查看端點、可接受的輸入、該工具是否以批次方式執行，以及每個欄位的預設值與允許的值。輸入未知的工具 ID 時會給出建議，拼錯的 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 設為自架 pdfx-server 的位址，或以 --api-base 傳入。如果你的伺服器需要金鑰，再加上 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 結束。在批次中，這樣的檔案算作未符合，而不是失敗。