适用于 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。许可证页面上的密钥查询解释了结果的含义。许可证包含什么以及如何购买，见许可证页面。

转换项目

在要转换的项目文件夹中打开终端，并在那里启动你的智能体：

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

然后只需给智能体一条命令：

就这样。你不需要运行 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 应用是用 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。它属于你，不与我们绑定。主题不连接任何地方。如何点击编辑，见应用文档中的 Visual Edit 部分。

哪些数据会离开你的电脑

你的电脑负责浏览器相关的工作：构建页面、比较截图，以及在 Docker 中运行临时 WordPress 做最后检查。主题本身由 html2wp 服务生成。因此，插件会把构建好的网站发给服务，再取回主题。

主题检查在你这边运行，所以服务看不到检查结果。因此，插件会在最后把结果发给服务。这是必需的：上一次转换发送结果之前，服务不会开始下一次转换。

• 发送的内容：检查的名称、是否通过、页面数量、最差的匹配百分比，以及未通过页面的短名称，例如 about 或 pricing。
• 不发送的内容：网站的地址或域名、代码、文字、截图、文件路径、许可证密钥或网站名称。插件只发送预先定义的字段，不发送其他任何内容。
• 自己核实：命令 send-verdicts.sh <workspace> --dry-run 会打印将要发送的确切内容，但不发送任何东西。它是一个可以阅读的短脚本。

插件不发送其他任何数据，做好的主题则完全不发送任何东西。完整说明（包括我们保留数据多久）见隐私页面。

报告 bug

如果是转换器本身出错，请用这条命令报告：

每份报告都有人阅读。修复随后会进入服务，所以每个用户都能受益。