從 WordPress 搬家，最難的通常不是挑新的框架，而是把文章、圖片和原本的網址一起帶走。搬運途中只要少一張圖，文章就可能變成「文字很完整，配圖正在度假」。

這篇會用 Eleventy 官方的 @11ty/import，示範如何從 WordPress REST API 匯入內容、預覽變更、檢查輸出，再把檔案放進 11ty 專案。你也會知道它能處理什麼，以及哪些整理工作仍然要自己完成。

目錄

先認識 @11ty/import

@11ty/import 是 Eleventy 提供的命令列匯入工具，可以從多種來源取得內容。WordPress 匯入器會讀取網站的 REST API，把文章內容寫成專案裡的靜態檔案，並下載文章中引用的資產。

Eleventy 官方文件目前的 WordPress 教學使用的是這個工具；文件頁面也同時標示 Eleventy 3.1.6 Stable 與 4.0.0 Canary。不過，這不代表 @11ty/import 的版本會跟 Eleventy 核心版本同步。執行時，實際使用的匯入器版本仍以套件管理器解析到的版本為準，所以不要把某個範例輸出的版本數字當成固定保證。

為什麼不只匯出一份 WXR？

WordPress 後台的「工具 → 匯出」可以產生 WXR XML，適合保留文章、頁面、分類和標籤等內容資料。不過，WXR 主要是 WordPress 內容交換格式，不是直接放進 Eleventy 就能完成的 Markdown 專案。

如果你的目標是把文章放進 Git，再由 11ty 產生靜態頁面，還需要把 XML 轉成 Markdown、處理圖片，並檢查圖片連結。@11ty/import 走的是另一條路：直接從 WordPress 網站取得內容，同時下載內容裡參照到的資產。

開始匯入 WordPress

1. 先用 --dryrun 預覽

先切換到你準備放置匯入檔案的專案目錄，再執行：

npx @11ty/import wordpress https://your-site.com/ --dryrun

如果你使用 pnpm，也可以寫成：

pnpm dlx @11ty/import wordpress https://your-site.com/ --dryrun

--dryrun 會先預覽可能的變更，不直接寫入檔案。第一次搬家建議先做這一步，讓你有機會確認來源網站、輸出位置和資料量；畢竟把錯的網站搬得很有效率，仍然算是搬錯家。

2. 執行正式匯入

確認預覽結果沒有問題後，移除 --dryrun：

npx @11ty/import wordpress https://your-site.com/

工具會透過 WordPress REST API 取得文章，並依照原本的網址結構寫入檔案。預設輸出格式是 Markdown，也可以使用 --format=html 改用原始 HTML。

匯入數量較多時，終端機可能會顯示成功處理的文件、資產和錯誤數量。看到錯誤數量不代表所有內容都失敗，但要逐項檢查，不能只看成功的總數就按下慶祝用的咖啡機。

3. 需要時指定輸出目錄

如果你不想把匯入結果寫在目前目錄，可以用 --output 指定根目錄：

npx @11ty/import wordpress https://your-site.com/ --output=content

官方文件說明，匯入器會維持內容原本的網址結構；--output 只會改變輸出的根目錄。實際使用時，仍要依你的 Eleventy input 設定調整位置，不要直接假設所有專案都使用 content/。

匯入後會得到什麼？

匯入器的預設輸出大致可以想成：

your-project/
├── assets/
│   ├── image-1.jpg
│   └── image-2.png
└── article-slug.md

實際目錄會受到文章網址、--output、資產參照方式和工具版本影響，所以這是一個理解用途的示意，不是固定檔案樹。

它會做幾件重要的事：

  • 把 WordPress 內容寫入本機檔案。
  • 下載文章內容中引用的圖片、影片或其他資產。
  • 修改內容中的參照，讓它們指向本機檔案。
  • 預設不覆寫既有內容；需要更新既有檔案時，才使用 --overwrite。
  • 將下載結果快取在本機，方便中斷後繼續處理大型匯入。

資產參照方式也可以調整。預設是相對路徑；如果你希望資產和每篇文章放在一起，可以使用 --assetrefs=colocate：

npx @11ty/import wordpress https://your-site.com/ --assetrefs=colocate

這些選項決定檔案怎麼落地，並不會自動替你補上本站需要的 front matter、分類、摘要或版型。WordPress 外掛留下的 shortcode，也可能需要另外清理；匯入工具很勤勞，但它不是內容考古學家。

把檔案接到 Eleventy

1. 確認輸入目錄

把匯入產生的 Markdown 和資產放到專案的 Eleventy 輸入目錄。以常見的專案結構為例：

content/
└── blog/
    ├── article-slug.md
    └── assets/

但 Eleventy 並沒有規定每個專案一定要使用 content/blog/。請先查看自己的設定檔，確認輸入目錄、模板預設資料和資產處理方式。

2. 補上專案需要的 front matter

匯入檔案能提供文章內容，不代表它會符合你的網站資料模型。以本網站為例，文章還需要依專案規則補上 title、date、description、分類和標籤等欄位：

---
title: 文章標題
description: 文章摘要
date: 2025-12-15
metadata:
  categories:
    - 靜態網站
tags:
  - wordpress
  - eleventy
---

不要直接把這段範例原封不動套到所有專案；日期格式、分類欄位和 layout 都是專案自己的約定。先讓資料符合網站的 schema，再讓 Eleventy 負責渲染，除錯時會輕鬆很多。

3. 啟動本機伺服器

在本網站裡，可以用以下指令啟動開發伺服器：

pnpm run start

接著開啟文章的輸出網址，例如：

http://localhost:8080/文章名稱/

實際網址會依 front matter、檔名和 Eleventy 設定而定。請檢查以下幾項：

  • 文章標題、日期和摘要是否正確。
  • 文章內的圖片是否能載入。
  • 舊網址是否需要保留，或要加上重新導向。
  • shortcode、嵌入內容和 HTML 是否需要改寫。
  • 文章是否套用了正確的 layout、CSS 和網站功能。

如果文字出現、圖片也能載入，但樣式沒有跟著 WordPress 過來，這通常不是匯入失敗。WordPress 的佈景主題和外掛不會因為文章被轉成 Markdown，就自動變成 Eleventy 的模板與 CSS；內容搬家成功，網站外觀仍要重新接回來。

選一個 11ty 起始專案

內容檔案整理好後，下一步是選擇 Eleventy starter。這不是 @11ty/import 的必要步驟，而是你要怎麼建立新網站的選擇。

eleventy-base-blog

eleventy-base-blog 是 Eleventy 官方 GitHub 組織裡的部落格 starter，結構相對精簡，適合想自己逐步加入功能的人。

它的優點是容易讀懂、方便修改；相對地，搜尋、SEO、設計系統和進階圖片處理等功能，通常需要你自行整合。簡單不是缺點，只是代表你的待辦清單會比較誠實。

eleventy-excellent

eleventy-excellent 是社群 starter，提供更完整的網站結構和功能範例。它適合想先有一個較完整起點的人，但採用前要先閱讀它的技術選擇，確認是否符合你的維護方式。

怎麼選？

如果你想理解每一層是怎麼組起來的，可以從精簡的 starter 開始；如果你更在意快速得到完整網站，再評估功能較多的 starter。無論選哪個，都建議先用少量文章試跑一次，再開始全站匯入。

從 WordPress 搬出來，不等於全部結束

@11ty/import 解決的是「把內容和資產帶到本機」這一段。真正完成遷移，還要做內容清理、front matter 對應、版型重建、網址重新導向，以及逐頁檢查圖片和嵌入內容。

比較穩妥的流程是：

  1. 用 --dryrun 預覽。
  2. 先匯入少量內容驗證結構。
  3. 檢查 Markdown、圖片和網址。
  4. 補上 Eleventy 專案需要的資料欄位。
  5. 再匯入完整內容。
  6. 啟動本機網站，逐頁驗收。

這樣做雖然多幾個步驟，卻能避免「所有文章一次搬完，最後才發現圖片路徑全錯」的劇情。WordPress 可以先告別，但除錯不會因為搬家而自動搬走。

參考資料