適用於 Claude Code 和 Codex 的 html2wp 外掛

安裝

外掛放在兩個 GitHub 儲存庫中，一個用於 Claude Code，一個用於 Codex。兩者內容相同，版本號也相同，區別只在於各個工具載入它們的方式。請安裝與你的工具對應的那一個，因為另一個無法載入。

切換到你的工具，依次執行這兩行指令：

第一行指令從 GitHub 新增外掛目錄（即 marketplace）。第二行指令再從中安裝 html2wp。Codex 需要自己的儲存庫，因為它透過 .agents/plugins/marketplace.json 檔案查詢外掛，而 Claude Code 的儲存庫裡沒有這個檔案。

更新

更新指令在兩個工具中名稱不同。在 Codex 中是 upgrade，在 Claude Code 中是 update：

要檢視已安裝的版本，在 Codex 中執行 codex plugin list。在 Claude Code 中，進入 /plugin → Marketplaces → html2wp。

如果更新後 Codex 中的版本沒有變化，說明 Codex 存著一份舊副本。刪除它，然後重新安裝外掛：

如果這樣還不行，Codex 裡可能還有一份手動安裝留下的、不同的舊副本。指令 codex plugin marketplace list 會列出所有目錄。如果你在其中看到 html2wp@<other-name>，用 codex plugin remove html2wp@<that-name> 刪除它。

大部分工作在 html2wp 服務中進行，而服務會自行更新，所以你的下一次轉換就已經在用新版本。你只需要更新在你電腦上執行的部分：檢查、指令碼和外發資料過濾器。每個版本的變更見 GitHub 上的提交歷史。

系統需求

你不需要自己檢查。開始轉換時，外掛會先檢查你的電腦，並列出缺少的東西：

Node.js                ok        v22.14.0
Python                 ok        3.12.4
Playwright             MISSING   mirroring, prerendering and every screenshot
Docker                 NOT RUNNING  installed, but the daemon is not up

對於只安裝到你使用者目錄中的套件，例如 Playwright 或 chromium 瀏覽器，外掛會主動提出幫你安裝。每個指令執行前它都會先詢問。對於會改動整個系統的東西，例如 Docker Desktop 或更新版本的 Node.js，它只會報告，然後等你自己安裝。

如果你想手動安裝 Python 套件：

使用哪個模型

轉換過程中，AI 需要做很多決定。例如：哪個頁面是首頁，某項檢查為什麼失敗，或者客戶是否能察覺兩張截圖之間的差異。因此，模型的選擇比其他任何設定都更影響結果。

在 Claude Code 中，Opus 5 負責主要工作，Fable 5 在重要決定上提供意見，而轉換最常出錯的地方正是這些決定。

授權金鑰

免費版不需要金鑰，可以跳過本節。如果你有授權，請在第一次轉換之前把金鑰儲存到電腦上。這只需要做一次，在任何資料夾中都可以：

你也可以透過環境變數 H2WP_KEY 傳入金鑰，它的優先順序高於檔案。用檔案更安全，因為這樣金鑰不會留在終端機歷史紀錄裡。

這個檔案存放的是你購買 Pro 時獲得的 html2wp 授權金鑰。Visual Edit Pro 金鑰不放在這裡。它要在你所編輯網站上的 Visual Edit 外掛中輸入，並且不能用於轉換。

要了解金鑰是否有效、能用來做什麼、有效期到什麼時候，執行 npx html2wp-license YOUR-KEY。授權頁面上的金鑰查詢解釋了結果的含義。授權包含什麼以及如何購買，見授權頁面。

轉換專案

在要轉換的專案資料夾中開啟終端機，並在那裡啟動你的 AI 代理：

如果你用的是 Claude Code，最後一行輸入 claude，而不是 codex。

然後只需給 AI 代理一行指令：

就這樣。你不需要執行 npm install 或 npm run build，也不需要做任何設定。來自 Bolt、v0、shadcn 或 Next.js 匯出的專案，轉換方式完全一樣。你也可以在 Claude Code 中只輸入 /html2wp:html2wp，或者讓 Codex 使用 html2wp。然後外掛會問你要轉換什麼。

轉換的最初幾分鐘

> convert this project

  Checking this machine first…
    Node.js     ok    v22.14.0
    Playwright  MISSING
  Two Python packages are missing. Shall I install them? (they go in your
  user directory, no root)

> yes

  … installed. Building the project, then prerendering it.
  7 routes found: /, /about, /pricing, /blog, /blog/launch, /contact, /faq
  Decided: /blog is the listing, /blog/launch an article, the rest are pages.
  Written to the manifest; carrying on.

在最後幾行中，外掛記錄了它如何對頁面分類：/blog 是文章列表，/blog/launch 是一篇文章，其餘是普通頁面。最後請在做好的網站上檢查這個決定。

其他輸入

指令 convert this project 會轉換你當前所在的資料夾。如果檔案在別處，請輸入它們的路徑，例如 convert ./dist。

輸入必須始終在你的磁碟上。外掛不轉換線上網址。它需要的是建置網站的原始檔，而不是瀏覽器顯示的內容。

Lovable 專案如何轉換

Lovable App 是用 React 建置的。它的 index.html 只有一個空元素和一段指令碼，頁面只有在瀏覽器中才會成形。因此，外掛先建置專案，在真實瀏覽器中開啟，並把每個頁面儲存為完整的 HTML。它還會擷取只在指令碼執行後才出現的內容，例如展開的摺疊面板或下拉選單。然後，它用這些頁面產生佈景主題。詳情見 Lovable 轉 WordPress 指南。

它替你決定什麼

哪個頁面是什麼

有一個決定對結果影響最大：哪個頁面是首頁，哪個是文章列表，哪些是文章，哪些是商品。外掛會根據頁面程式碼判斷，把結論記下來，然後不經詢問繼續執行。只有在無法判斷時它才會停下來。例如，網站的頁面數超過了你的限額，或者兩個頁面看起來是同一個頁面。

如果判斷錯了，修正的代價很小。你更正分類，再執行一次轉換即可。這算重新執行，不計入你的轉換次數限制。

之後基本自動執行

Flash 大約需要半小時，Full 大約一小時，具體取決於頁面數量和電腦速度。在此期間，外掛會建置網站，與原版比較，並傳送到 html2wp 服務進行轉換。之後，它把做好的佈景主題安裝到你電腦上 Docker 中的臨時 WordPress 裡，並在那裡測試。

不能跳過的檢查

最後，外掛會把每個頁面和原版並排放在一張圖中給你看。請看每一張圖，並說出你看到了什麼。

你會得到什麼

• ZIP 格式的佈景主題。在 WordPress 後台的「外觀 → 佈景主題 → 安裝佈景主題 → 上傳佈景主題」中上傳。外掛根本不會建置有問題的佈景主題：例如 PHP 有語法錯誤、內容缺失、佈景主題截圖尺寸不對，或者商店裡無法購買任何東西。
• 報告 CONVERSION-REPORT.md，與 ZIP 在同一個資料夾中。它列出已轉換的頁面、已連線的選單、你在檢查中發現的所有問題、轉換中的每條警告，以及還需要做的事情。
• Visual Edit Lite 的連結，這是一款點選即可編輯的免費編輯器。編輯器不屬於佈景主題，沒有它佈景主題也能執行。Visual Edit Pro 是單獨的付費授權。

佈景主題是獨立的。頁面、部落格、表單、選單、SEO 和重新導向都是它程式碼的一部分，無需外掛即可執行。程式碼是可讀的 PHP、CSS 和 JavaScript。它屬於你，不與我們綁定。佈景主題不連線任何地方。如何點選編輯，見App 文件中的 Visual Edit 部分。

哪些資料會離開你的電腦

你的電腦負責瀏覽器相關的工作：建置頁面、比較截圖，以及在 Docker 中執行臨時 WordPress 做最後檢查。佈景主題本身由 html2wp 服務產生。因此，外掛會把建置好的網站發給服務，再取回佈景主題。

佈景主題檢查在你這邊執行，所以服務看不到檢查結果。因此，外掛會在最後把結果發給服務。這是必需的：上一次轉換傳送結果之前，服務不會開始下一次轉換。

• 傳送的內容：檢查的名稱、是否通過、頁面數量、最差的相符百分比，以及未通過頁面的短名稱，例如 about 或 pricing。
• 不傳送的內容：網址或網域、程式碼、文字、截圖、檔案路徑、授權金鑰或網站名稱。外掛只傳送預先定義的欄位，不傳送其他任何內容。
• 自己核實：指令 send-verdicts.sh <workspace> --dry-run 會列印將要傳送的確切內容，但不傳送任何東西。它是一個可以閱讀的短指令碼。

外掛不傳送其他任何資料，做好的佈景主題則完全不傳送任何東西。完整說明（包括我們保留資料多久）見隱私頁面。

報告 bug

如果是轉換器本身出錯，請用這行指令報告：

每份報告都有人閱讀。修復隨後會進入服務，所以每個使用者都能受益。