Python HTML to PDF 應用場景與工具選擇
常見應用場景與需求說明
將 HTML 內容轉換為 PDF 是許多企業與開發者在自動化流程、數位文件管理、報表產出等情境下的核心需求。常見應用包括：
- 自動產生報表：定期將動態網頁報表轉為 PDF，方便歸檔與分享。
- 電子發票/合約：將線上表單或合約內容轉為 PDF，便於存證與傳遞。
- 知識文件歸檔：將知識庫、教學內容等網頁轉為 PDF，便於離線閱讀或備份。
- 專案管理：自動化產生會議紀錄、任務清單等 PDF 文件，提升團隊協作效率。
主流工具比較（pdfkit vs WeasyPrint）
目前 Python 轉換 HTML 為 PDF 的主流方案有 pdfkit（基於 wkhtmltopdf）與 WeasyPrint。下表比較兩者特性：
| 工具 | 轉換引擎 | 跨平台 | CSS 支援 | 中文支援 | 圖片/字體嵌入 | 進階功能（頁眉頁腳等） | 安裝難易度 | 適用情境 |
|---|---|---|---|---|---|---|---|---|
| pdfkit | wkhtmltopdf | 是 | 高 | 佳 | 佳 | 支援 | 中 | 報表、合約、批次轉換 |
| WeasyPrint | 自有渲染引擎 | 是 | 高 | 佳 | 佳 | 部分支援 | 易 | 簡易報表、樣式較多 |
選擇建議：
– 若需高度還原網頁樣式、支援複雜分頁與頁眉頁腳，建議優先考慮 pdfkit。
– 若偏好純 Python 安裝、樣式以 CSS 為主，WeasyPrint 是輕量選擇。
安裝與環境設定
pdfkit 與 wkhtmltopdf 安裝步驟
pdfkit 依賴外部程式 wkhtmltopdf，安裝時需注意平台差異：
1. 安裝 pdfkit：
pip install pdfkit
2. 安裝 wkhtmltopdf：
– Windows：至 wkhtmltopdf 官網 下載對應版本，安裝後將路徑加入系統環境變數。
– macOS：可用 Homebrew 安裝：
bash
brew install wkhtmltopdf
– Linux（如 Ubuntu）：
bash
sudo apt-get install wkhtmltopdf
常見問題：
– 安裝後如遇「No wkhtmltopdf executable found」錯誤，需確認 wkhtmltopdf 路徑已加入系統環境變數，或於程式中手動指定路徑。
WeasyPrint 安裝與依賴說明
WeasyPrint 為純 Python 套件，但需安裝部分系統依賴（如 Cairo、Pango）：
1. 安裝 WeasyPrint：
pip install weasyprint
2. 安裝系統依賴：
– Windows：安裝 WeasyPrint 時會自動安裝大部分依賴，若遇缺失可參考官方文件。
– macOS：
bash
brew install cairo pango gdk-pixbuf libffi
– Linux（如 Ubuntu）：
bash
sudo apt-get install libpango1.0-0 libgdk-pixbuf2.0-0 libcairo2
注意事項：
WeasyPrint 支援大部分 CSS 樣式，但對於 JavaScript 動態渲染內容支援有限。
Python HTML 轉 PDF 基本教學
使用 pdfkit 轉換本地 HTML 檔案
將本地 HTML 檔案轉為 PDF，適合自動化產生靜態文件：
import pdfkit
pdfkit.from_file('input.html', 'output.pdf')
使用 pdfkit 轉換 HTML 字串
直接將程式產生的 HTML 字串轉為 PDF，適合動態內容：
html_content = '''
<html>
<head><title>範例</title></head>
<body><h1>自動產生報表</h1></body>
</html>
'''
pdfkit.from_string(html_content, 'output.pdf')
使用 pdfkit 轉換網頁 URL
可直接將線上網頁轉為 PDF，常用於歸檔或快照：
pdfkit.from_url('https://example.com', 'output.pdf')
進階參數範例：
options = {
'page-size': 'A4',
'margin-top': '10mm',
'margin-bottom': '10mm',
'encoding': "UTF-8",
'header-center': '公司報表',
}
pdfkit.from_file('input.html', 'output.pdf', options=options)
使用 WeasyPrint 轉換本地 HTML 檔案
WeasyPrint 操作簡單，適合純 Python 環境：
from weasyprint import HTML
HTML('input.html').write_pdf('output.pdf')
使用 WeasyPrint 轉換 HTML 字串
from weasyprint import HTML
html_content = '''
<html>
<head><title>範例</title></head>
<body><h1>自動產生報表</h1></body>
</html>
'''
HTML(string=html_content).write_pdf('output.pdf')
進階應用與常見問題
控制 PDF 樣式（CSS、字體、圖片、中文）
- 內嵌 CSS：可於
<style>標籤內直接定義樣式。 - 外部 CSS：pdfkit 需確保 CSS 路徑正確，WeasyPrint 支援本地與遠端 CSS。
- 字體嵌入：建議使用 web 字體（@font-face），並將字體檔案與 HTML 放同一資料夾。
- 圖片處理：圖片需使用絕對路徑或 base64 內嵌，確保轉換時可正確讀取。
- 中文支援：如遇亂碼，請指定支援中文的字體，並於 CSS 設定
font-family。
範例：
<style>
body { font-family: "Noto Sans TC", "微軟正黑體", Arial, sans-serif; }
h1 { color: #0072C6; }
</style>
設定頁面尺寸、邊界、分頁、頁眉頁腳
- pdfkit：可透過
options參數自訂頁面尺寸、邊界、分頁、頁眉頁腳內容。 - WeasyPrint：支援 CSS
@page規則設定紙張大小與邊界，但對頁眉頁腳支援較有限。
pdfkit 進階設定範例：
options = {
'page-size': 'A4',
'margin-top': '15mm',
'margin-bottom': '15mm',
'footer-right': '[page]/[topage]',
}
pdfkit.from_file('input.html', 'output.pdf', options=options)
WeasyPrint CSS 分頁範例：
@page {
size: A4;
margin: 20mm;
}
常見錯誤與排查指引
- No wkhtmltopdf executable found：請確認 wkhtmltopdf 已安裝並加入環境變數，或於程式中指定路徑。
- 圖片、CSS 無法顯示：請檢查資源路徑是否為絕對路徑或正確的 URL。
- 中文亂碼：需於 CSS 指定支援中文的字體，並確認字體檔案存在。
- WeasyPrint 缺少依賴：請依據系統安裝 Cairo、Pango 等依賴。
自動化與批次轉換範例
若需批次將多個 HTML 檔案轉為 PDF，可利用迴圈自動處理：
import pdfkit
import os
html_files = [f for f in os.listdir('html_folder') if f.endswith('.html')]
for file in html_files:
output_pdf = file.replace('.html', '.pdf')
pdfkit.from_file(os.path.join('html_folder', file), os.path.join('pdf_folder', output_pdf))
此方法常用於自動產生多份報表、發票或批次歸檔。
工具選擇建議與實務應用
各工具適用情境與優缺點
- pdfkit（wkhtmltopdf）
適合需高度還原網頁、支援複雜分頁與頁眉頁腳的需求，如財務報表、專案進度文件。若需與團隊協作或進行自動化流程，建議可結合 Monday.com 等專案管理平台，將產生的 PDF 報表自動整合至任務流程中。 - WeasyPrint
適合純 Python 環境、樣式以 CSS 為主的簡易報表或教學文件。若需進行文件簽署或進階 PDF 編輯，可考慮搭配 pdfFiller 等工具進行後續處理。
常見問答（FAQ）
如何處理中文亂碼？
請於 HTML 的 CSS 標籤中指定支援中文的字體，例如 "Noto Sans TC"、"微軟正黑體"，並確認字體檔案已正確安裝於系統。
如何嵌入外部 CSS 或圖片？
- CSS：建議使用絕對路徑或將 CSS 內容直接寫入
<style>標籤。 - 圖片：使用絕對路徑或 base64 內嵌，避免相對路徑導致資源遺失。
如何加密 PDF 或加上浮水印？
pdfkit 與 WeasyPrint 本身不支援加密與浮水印，可於產生 PDF 後，利用如 pdfFiller 等專業工具進行加密、浮水印或電子簽署。
其他常見問題
- 如何處理 JavaScript 動態內容？
pdfkit（wkhtmltopdf）支援部分 JavaScript 渲染，但複雜互動內容建議先轉為靜態 HTML。 - 如何批次轉換多個檔案？
可利用 Python 迴圈批次處理，詳見上方自動化範例。
結論與行動建議
Python 提供多元且彈性的 HTML 轉 PDF 解決方案，無論是報表自動化、文件歸檔還是專案管理，都能大幅提升工作效率。選擇合適的工具（如 pdfkit 或 WeasyPrint），並善用進階參數與樣式設定，可確保 PDF 文件專業且美觀。若需進一步整合團隊協作或進階 PDF 編輯，建議搭配 Monday.com、pdfFiller 等平台，打造高效的數位工作流程。
