经典主题迁移到块主题：模板、菜单与自定义字段怎么搬 (2)

准备：环境与备份

2026 年 WordPress 已全面进入区块编辑器时代，核心对块主题（Block Themes）支持成熟，但大量站点仍跑在经典主题（Classic Themes）上。迁移前必须准备：本地或预发环境、WP-CLI、数据库导出、以及一份当前主题的副本。执行 wp db export backup-2026.sql 与整站文件打包。确认运行的是 2026 年主流版本，主题目录位于 wp-content/themes/your-theme。

在预发环境而非生产直接操作，是避免线上事故的第一原则。若你需要专业迁移支持，可参考 WordPress 网站迁移 服务页了解完整交付流程。

实施步骤：从经典到块主题的完整流程

1. 备份数据库与文件，在预发环境还原。
2. 建立块主题骨架：创建 style.css、theme.json、templates/ 与 parts/ 目录。
3. 将 PHP 模板按层级映射为 .html 块模板文件。
4. 迁移菜单到导航区块，widget 到区块小工具或模板部件。
5. 核对固定链接设置与模板层级，保证 URL 不变。
6. 执行回归检查清单，验证无误后再上线；异常则用备份回滚。

PHP 模板到 html 模板映射

经典主题用 index.php、single.php、page.php、header.php 等 PHP 文件，靠 get_header() 拼接；块主题把结构放进 templates/ 下的 .html 文件，由 theme.json 控制全局样式，部件放 parts/。

映射规则

WordPress 模板层级在两种主题中一致，只是后缀不同：single.php 对应 templates/single.html，page.php 对应 templates/page.html，index.php 对应 templates/index.html。header.php 拆成 parts/header.html，用区块 <!-- wp:template-part {"slug":"header"} /--> 引入。

可复制的块模板示例

下面是一个最小 templates/single.html，把文章标题与内容用核心区块表达：

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

注意：JSON 属性里的 <、>、& 必须写成 <、>、&，否则块解析失败。旧主题中写在 functions.php 里的动态逻辑，若无法用区块表达，应通过区块编辑器官方手册推荐的动态区块或短代码兼容层处理。

菜单与 widget 迁移

经典主题用 wp_nav_menu() 输出菜单，widget 存在 wp_options 的 widget_* 记录里；块主题用「导航」区块与区块小工具（Block Widgets）。

菜单迁移操作

进入「外观 → 编辑器」，在 parts/header.html 中加入导航区块：

<!-- wp:navigation {"ref":123} /-->

其中 123 是「外观 → 菜单」里已有菜单对应的 wp_navigation 文章 ID。可用 WP-CLI 查：wp post list --post_type=wp_navigation。旧 wp_nav_menu 的菜单位置（theme_location）不再生效，需在编辑器里手动指派导航区块到该菜单。

widget 迁移操作

块主题下「小工具」界面已区块化。旧 widget 数据不会自动变区块，需逐个在「外观 → 小工具」里用「旧版小工具」区块包裹，或重建为段落/列表/搜索等区块。侧边栏区域改为 parts/sidebar.html（若保留）或用 templates/page.html 中的列布局承载。

踩坑：直接删旧 widget 会导致内容丢失；应先在预发导出 wp_options 中 widget_ 前缀项再操作。更多关于可复用结构的做法，可看 可复用区块样板怎么做才有复用价值。

避免 URL 变动

URL 变动是迁移中最致命的 SEO 事故。块主题不改变固定链接结构，但模板文件名变化若伴随 rewrite 刷新不当，会出现 404。

操作与验证

迁移前后都执行：wp rewrite list 对比规则；在「设置 → 固定链接」点两次保存以刷新。用 wp post list --fields=ID,post_name 抽查别名，并跑 wp eval 'echo home_url("/sample-page/");' 确认首页与文章页可达。只要 post_name 与固定链接设置不变，URL 就不会变。

失败回退：若出现 404，恢复备份的 .htaccess（Apache）或 nginx 配置，并执行 wp rewrite flush。

迁移后回归检查

上线前必须跑回归。检查项写成清单逐条打勾。

检查项	方法	通过标准
模板渲染	访问 /、/文章、/页面	无 PHP 报错，块模板输出
菜单显示	前台 header 区域	导航区块列出原菜单项
URL 一致	对比迁移前 sitemap	完全一致，无 404
自定义字段	编辑文章看 meta 框	旧 meta 值仍显示

自定义字段（Post Meta）在块主题中不会丢，它们存在 postmeta 表；但若旧主题用 the_meta() 输出，需在 single.html 里改用动态区块或 render_callback 读取。用 wp post meta list <id> 验证数据仍在。

若任一检查失败：用备份 SQL 与主题目录覆盖回预发，即完成回滚；生产环境始终保留最近两份备份。

常见问题

迁移后旧菜单不显示了怎么办？

旧 wp_nav_menu 位置失效，需在站点编辑器里把导航区块绑定到对应 wp_navigation 文章，并清除缓存。

块主题还能用 PHP 模板吗？

可以共存：把 PHP 放 templates/ 外或做兼容，但推荐全量转 html 以获完整 FSE 能力。

自定义字段会丢吗？

不会丢，数据在 postmeta；只是显示方式要从 PHP 函数改为区块或动态区块渲染。

可执行动作清单

1. 在预发环境导出 2026 年当前库与文件备份。
2. 建 theme.json 与 templates/、parts/ 骨架。
3. 按层级把 PHP 改写为 html 块模板并转义特殊字符。
4. 用导航区块接旧菜单，区块化 widget。
5. 刷新 rewrite 并跑回归表，异常即回滚。

需要专业团队接手迁移？访问 https://runokwp.com/services/website-migration/ 获取 2026 年站点迁移服务，我们提供备份、映射与回滚保障。

参考资料与延伸阅读

• WordPress 开发者文档
• WordPress 主题开发手册
• WordPress 插件开发手册