@willh/pdf-to-images

一個簡單高效的 CLI 工具，可將 PDF 頁面轉換為獨立的 PNG 圖片。

功能特色

• 🚀 將 PDF 的每一頁轉換為高品質 PNG 圖片
• 📁 自動輸出目錄管理，支援自動編號
• 🔍 輸入驗證，檢查檔案存在性和副檔名
• 📊 轉換過程進度追蹤
• 🔊 詳細模式提供完整日誌記錄
• ⚡️ 高品質輸出（3 倍縮放，約 216 DPI）

安裝

您可以使用 npx 直接執行此工具，無需安裝：

npx -y @willh/pdf-to-images -i sample.pdf -o output

或全域安裝：

npm install -g @willh/pdf-to-images

使用方式

基本用法

將 PDF 檔案轉換為圖片，輸出到預設的 output 目錄：

npx -y @willh/pdf-to-images -i sample.pdf -o output

選項

• -i, --input <path> - （必要） 輸入 PDF 檔案路徑
• -o, --output <path> - 輸出目錄路徑（預設：output）
  • 如果目錄已存在，將自動附加數字（例如：output1、output2 等）
• -f, --force - 覆寫現有的輸出目錄和檔案（停用自動編號功能）
• --engine <engine> - 渲染引擎：pdfjs（預設）或 chrome
  • chrome 使用無頭 Chrome/Edge 來渲染頁面，能更好地匹配瀏覽器的 PDF 渲染和系統字型替換
• --chrome-path <path> - Chrome/Edge 可執行檔路徑（僅用於 --engine=chrome）；也可設定 CHROME_PATH 環境變數
• --verbose - 啟用詳細日誌記錄，顯示完整輸出
• -v, --version - 顯示版本號碼
• -h, --help - 顯示說明資訊

範例

使用詳細輸出進行轉換：

npx -y @willh/pdf-to-images -i document.pdf -o images --verbose

使用無頭 Chrome 渲染（更好的系統字型替換）：

npx -y @willh/pdf-to-images -i document.pdf -o images --engine chrome

覆寫現有目錄中的輸出檔案：

npx -y @willh/pdf-to-images -i document.pdf -o images -f

檢查版本：

npx -y @willh/pdf-to-images -v

取得說明：

npx -y @willh/pdf-to-images -h

輸出

此工具將會：

1. 建立輸出目錄（如果不存在）
2. 將每一頁轉換為 PNG 檔案，檔名格式為 {檔名}-{頁碼}.png
   • 頁碼會補零（例如：少於 100 頁時為 01、02，100 頁以上為 001、002）
3. 在轉換過程中顯示進度

輸出檔案範例：

output/
├── sample-01.png
├── sample-02.png
├── sample-03.png
└── ...

錯誤處理

此工具會驗證：

• ✅ 輸入檔案存在
• ✅ 輸入檔案具有 .pdf 副檔名
• ✅ 輸出目錄可以建立
• ✅ PDF 檔案有效且可讀取

如果任何驗證失敗，工具將會顯示錯誤訊息並結束執行。

系統需求

• Node.js >= 20.16.0
• CI 使用 Node.js 20.16.x 和 22.x

授權

MIT License - Copyright (c) 2025 Will 保哥

作者

Will 保哥

原始碼庫

https://github.com/doggy8088/pdf-to-images

問題回報

回報問題請至：https://github.com/doggy8088/pdf-to-images/issues