跳至主要內容

Jia-Yin2025/10/20大約 8 分鐘

以下是針對「用 Python 結合 Word template 製作 Word 檔案」的詳細教學說明，同時包含可用的函式庫資源、實作步驟、範例程式碼與注意事項。

一、為什麼＋何時會想這麼做

當你有以下需求時，就很適合使用 Python ＋ Word template 的方法來產出 Word 檔案：

  • 需要產出大量格式相同但內容不同的 Word 文件（例如：合約模板、報告、邀請函）
  • 想用已有的 Word 檔（含版面、樣式、頁首／頁尾）當成模板，而不是完全從零撰寫
  • 希望自動化產出流程，如從 Excel、資料庫中讀取資料，然後填入 Word 模板
  • 想整合入 Python 工作流程／系統（報表系統、網頁服務）

優點包括：

  • 模板在 Word 裡先設計好 → 保持版面一致、且樣式可控
  • 在 Python 裡只需填入變數／合併資料，不需從頭建立版面
  • 可批次、程式化、自動化，節省手動複製貼上，降低錯誤

但也要注意：

  • 模板要事先準備好（版面、樣式、變數標記）
  • 某些樣式或 Word 的進階功能（如複雜欄位、巨集、特殊物件）可能不完全支援
  • 若跑批次大量文件／產生 PDF／版面控制，還是要測試版面是否正確

二、推薦的 Python 資源（函式庫／工具）

以下列出幾項常用、且社群活躍的 Python 函式庫／工具，可用於搭配 Word 模板製作 Word 文件。

函式庫功能簡介特點
python‑docx基礎的 .docx 檔案讀寫／建立函式庫。可打開 . docx 檔、編輯段落、表格、樣式等。(python-docx.readthedocs.io)非專門針對模板變量替換（需手動尋找段落、run 等）
python‑docx‑template基於 python-docx ＋ Jinja2 模板語法，可在 Word 模板中插入類似 {{variable}} 的標記，再由 Python 填入資料。(docxtpl.readthedocs.io)模板設計彈性高，支援表格／條件／迴圈等較複雜場景
docx‑mailmerge專門用於 Word 的 mail merge（合併字段）功能：在 Word 模板中定義 MergeField 欄位，然後用 Python 替換。(PyPI)適合「有 MergeField 欄位」的 Word 模板，流程較接近傳統 Word mail merge
Aspose.Words for Python via .NET商業級解決方案，支援 mail merge 、模板變量、格式控制、轉 PDF 等功能。(products.aspose.com)功能強大但可能需付費／商用授權
其他如將 Word 合併／組裝功能：docxcompose、pypandoc 等。(freecodecamp.org)若需要「合併多份 Word」或轉檔可參考

建議選用：如果你是第一次或需求中等，推薦使用 python-docx-template，其設計模板的方式較為直觀。若模板已用 Word 的 MergeField 功能建立，或你習慣於 mail merge 流程，則 docx-mailmerge 也非常適合。

三、操作流程（從設計模板 → Python 填入 → 產出）

以下依序說明典型的操作步驟。

1. 預備模板（在 Word 中）

  • 用 Microsoft Word （或其他支援 . docx 的編輯器）設計你的模板檔案，例如 template.docx。

  • 在版面中留出「變數位置」：例如：「姓名： 」、「日期： 」或使用 MergeField 格式。

    • 若使用 python-docx-template：可在 Word 內直接輸入 {{ variable_name }} 或使用 Jinja2 語法（也可插入 for 迴圈、條件）(Bays Consulting)
    • 若使用 docx-mailmerge：需在 Word 中插入 MergeField 欄位（使用 Word 的「插入 → 快速部件 → 欄位 → MergeField」）(pbpython.com)

  • 儲存模板為 .docx 格式。建議命名為 template.docx 或 report_template.docx。

  • 若有表格、頁首／頁尾、圖片、樣式，建議先在模板中設計好，確保 PDF 或列印時格式一致。

2. 在 Python 環境中安裝所需函式庫

例如，使用 pip 安裝：

pip install python-docx-template
# 或者
pip install docx-mailmerge

以上安裝方式取決於你選的模板技術。 參考：(PyPI)

3. 撰寫 Python 程式，讀入模板並填入資料

下面分兩種常見方式來說明：

(1) 使用 python-docx-template

範例程式碼：

from docxtpl import DocxTemplate

tpl = DocxTemplate("template.docx")

context = {
    "name": "王小明",
    "date": "2025-10-20",
    "amount": "NT$ 10,000",
    # 若有列表／表格資料：
    "items": [
        {"desc": "項目 A", "qty": 2, "price": 5000},
        {"desc": "項目 B", "qty": 1, "price": 5000},
    ]
}

tpl.render(context)
tpl.save("output_filled.docx")

說明：

  • template.docx 是你的模板檔案。
  • context 是一個 dict ，鍵對應模板裡 {{ name }} 等變數。
  • 若模板中含有表格、清單、條件語法（如：{% for item in items %}）也可支援。(Medium)
  • 最後 .save() 出檔案 output_filled.docx。

(2) 使用 docx-mailmerge

範例程式碼：

from mailmerge import MailMerge

template = "template_merge.docx"
with MailMerge(template) as document:
    print(document.get_merge_fields())  # 可印出模板中所有欄位名稱
    document.merge(
        name="王小明",
        date="2025-10-20",
        amount="NT$ 10,000"
    )
    document.write("output_merge.docx")

說明：

  • 模板需在 Word 中設定 MergeField 欄位。(pbpython.com)
  • get_merge_fields() 可以列出所有可替換欄位名稱。
  • .merge() 傳入對應欄位的鍵值。
  • 可做批次資料，例如從 CSV／Excel 讀取多筆，分別產出多份文件。(Mailtrap)

4. 進階應用（表格、迴圈、多筆資料、Web 服務整合）

  • 若你的文件內有「明細表格／多筆資料列」：在 python-docx-template 中可以使用 Jinja2 的迴圈語法，例如：

    {% for item in items %}
| {{ item.desc }} | {{ item.qty }} | {{ item.price }} |
{% endfor %}

    程式中填 items 為列表即可。這類用法在文章中亦有討論。(Medium)

  • 若從 Excel／CSV 讀取資料：可搭配 pandas 或 openpyxl 先載入資料，再迴圈填入模板。文章中有以 Excel 為例說明。(Perfect Doc Studio)

  • 若你的 Python 程式是作為 Web 服務（例如使用 FastAPI）自動產出 Word 檔案並回傳給使用者下載，也可用 python-docx-template 做為底層模版引擎。(DEV Community)

5. 儲存與輸出／後處理

  • 儲出為 .docx 檔案後，你可讓使用者下載、或轉換為 PDF（視需求）。
  • 如果要轉 PDF ：因 Word 本身不一定跨平台支援，你可考慮用 LibreOffice 指令列轉檔、或使用商用庫（如 Aspose）支援轉 PDF。
  • 注意檔案命名、路徑、批次輸出時避免覆蓋、並適當設置 UTF-8 編碼／字體／樣式。

四、模板設計與實作範例

以下提供一個簡單完整流程範例，讓你快速上手。

範例場景

我們要產出「報告合約」文件，每份內容包含「顧客姓名」「報告日期」「產品清單（多筆）」。

(1) 建立 Word 模板 (template.docx)

在 Word 中撰寫如下內容（用 python-docx-template 方式）：

合約報告

客戶姓名： {{ name }}
報告日期： {{ date }}

產品明細：
| 項目       | 數量 | 價格       |
|------------|------|------------|
{% for item in items %}
| {{ item.desc }} | {{ item.qty }} | {{ item.price }} |
{% endfor %}

感謝您的合作！

設好表格樣式、版面、頁首、頁尾等，然後儲存為 template.docx。

(2) 撰寫 Python 程式

from docxtpl import DocxTemplate

tpl = DocxTemplate("template.docx")

data = {
    "name": "張三",
    "date": "2025-10-20",
    "items": [
        {"desc": "產品 A", "qty": 3, "price": "NT$ 3000"},
        {"desc": "產品 B", "qty": 1, "price": "NT$ 1500"},
    ]
}

tpl.render(data)
output_path = "報告_張三.docx"
tpl.save(output_path)

print(f"已產出 {output_path}")

執行後你會得到 報告_張三.docx，內容中 、 及 items 的多筆表格皆已替換。

(3) 若要批次產出多筆

from docxtpl import DocxTemplate
import pandas as pd

tpl = DocxTemplate("template.docx")

df = pd.read_excel("data.xlsx")  # 假設欄位：name,date,desc,qty,price

for name, group in df.groupby("name"):
    items = group.apply(lambda row: {"desc": row["desc"], "qty": row["qty"], "price": row["price"]}, axis=1).tolist()
    data = {
        "name": name,
        "date": group["date"].iloc[0],
        "items": items
    }
    output = f"報告_{name}.docx"
    tpl.render(data)
    tpl.save(output)
    print(f"產出 {output}")

這樣你就可以依 Excel 資料，自動產出多份 Word 文件。

五、注意事項與常見問題

  • 字體／樣式問題：在模板中先設好字體、段落、標題樣式；若用 Python 替換變數時，注意變數替換後是否影響原樣式。
  • 圖片／圖表支援：若模板中有圖片或圖表，確認函式庫是否支援你所需的操作，例如插入圖片、動態圖表等。
  • 表格與分頁：若資料很多、表格可能跨頁、或需分頁，建議在模板中先設好表格結構與樣式，並測試大量資料。
  • 批次檔案命名／覆蓋：產大量檔案時請做好命名規則、避免覆蓋、並注意目錄結構與權限。
  • 記憶體／效能：若產出大量（數千份以上）或含大量圖片／表格，可能需注意記憶體、處理效能、是否需分批處理。
  • 格式轉 PDF：若最終輸出為 PDF，則 . docx → PDF 的轉換可能要用到額外工具或服務。
  • 合併字段／遺漏變數：使用 docx-mailmerge 時，請先用 get_merge_fields() 檢查模板中所有欄位名稱。(pbpython.com)
  • 版面跑掉或格式錯亂：建議測試模板產出少量檔案，檢查版面是否如預期。特別是在跨平台或不同 Word 版本。
  • Unicode／中文支援：若文件含中文或其他非 ASCII 字元，確認字體已嵌入或樣式支援。
  • 版權或敏感資料：若模板含公司機密／私人資料，要注意權限、分享方式、刪除暫存檔案。
  • 版本控制：模板若修改，要記錄版本與變更，避免舊版程式繼續使用舊模板而造成混亂。

如果你願意，我可以為你 準備一個完整的 GitHub 範本專案（含模板、Python 程式、README、批次產出範例）你可以下載修改。你要不要？

Copyright © 2026 Jia-Yin