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

准备：先固化基线，别急着动模板

迁移前先冻结当前环境：记录 WordPress 版本、主题目录、活动 widget、菜单分配与固定链接结构。2026 年主流环境是 WordPress 6.8/6.9 + PHP 8.2/8.3，块主题完全成熟，但经典主题的 functions.php 里常塞了大量 add_action，必须先盘点。

wp core version
wp theme list --status=active
wp menu list --fields=term_id,name,locations
wp option get permalink_structure
wp db export backup-before-block-migration.sql

把经典主题目录整包复制一份到 wp-content/themes/ 作为只读参考，原主题在迁移完成前不要删除。定义验收清单：首页、文章页、分类页、单页、搜索结果、404、菜单下拉、侧边栏 widget 区域全部逐项签字。

PHP 模板到 html 模板映射

块主题不再用 PHP 渲染模板，而是用 templates/ 与 parts/ 下的 html 文件，样式集中在 theme.json。映射规则按经典模板优先级对照：

经典主题文件	块主题文件	说明
index.php	templates/index.html	兜底模板
single.php	templates/single.html	文章详情
page.php	templates/page.html	独立页面
archive.php / category.php	templates/archive.html	归档与分类
header.php	parts/header.html	站点头部
footer.php / sidebar.php	parts/footer.html、parts/sidebar.html	页脚与侧栏
404.php	templates/404.html	错误页

步骤

1. 在主题根目录建 templates/ 与 parts/、patterns/。
2. 从 index.php 提取 header/footer/sidebar 逻辑，分别写入对应 part，用 <!-- wp:template-part {"slug":"header"} --> 引用。
3. 循环体用 Query Loop 块重建，模板层级由 theme.json 的 customTemplates 与块模板文件自动识别。
4. PHP 里的条件输出改写成块属性，不支持的逻辑封装成短代码或在 functions.php 用 register_block_pattern 提供。

常见踩坑：header.php 中直接 wp_nav_menu() 的输出若没转成 Navigation 块，前台会显示异常或空白；theme.json 缺少 version 字段会导致样式编辑器报错。验证方式：外观 → 编辑器 → 模板能看到所有模板，逐一点击预览无 PHP 报错。

菜单与 widget 迁移

菜单数据存在数据库里，不会因换主题消失，但 Navigation 块读取的逻辑不同。先确认 wp_nav_menu 的 theme_location 注册项，在块主题的 functions.php 里保留同样注册：

register_nav_menus( array(
    'primary' => __( '主导航', 'mytheme' ),
    'footer'  => __( '页脚菜单', 'mytheme' ),
) );

然后用 Navigation 块在 parts/header.html 中替换原菜单调用，选择已有菜单项即可。Widget 方面，块主题用 Group 块加块小工具区域替代 register_sidebar()，在模板里用 <!-- wp:block {"ref":123} --> 复用已保存的区块。经典小工具内容可通过 wp widget list 导出核对，再手动搬进区块。

不要在块主题里继续注册旧式 sidebar，否则前后台表现不一致，排查成本极高。

避免 URL 变动

URL 变动是迁移中最容易被忽略的 SEO 杀手。模板文件名变化不会影响固定链接，但重建菜单、修改分类基名、误删重写规则都会。迁移前后执行：

wp option get permalink_structure
wp rewrite list --format=table
wp rewrite flush --hard

固定链接结构保持 /%postname%/ 或原有结构不变；如果经典主题注册过自定义文章类型的 rewrite slug，必须在块主题的 functions.php 中原样保留，改完刷新重写规则并检查 .htaccess 未被覆盖。用 curl 抽查 20 条代表性 URL：

for u in / /about/ /blog/2026/01/sample-post/ /category/news/; do
  printf '%s -> %sn' "$u" "$(curl -o /dev/null -s -w '%{http_code}' https://example.com$u)"
done

全部返回 200 且无 301 到新路径，才算通过。若出现 404，回到 设置 → 固定链接 保存一次触发 flush。

迁移后回归检查

回归检查要覆盖四层：内容、模板、交互、性能。内容层核对文章数量、分类计数、菜单项数量；模板层逐页打开截图比对；交互层测试搜索、分页、评论提交；性能层用 Query Monitor 检查是否新增重复查询。建议在预发布环境先跑一遍，确认后再切生产。

回滚

回滚必须能在 5 分钟内完成：保留原经典主题目录不删，切换回原主题即可恢复菜单与 widget 的旧渲染。数据库层用迁移前的 backup-before-block-migration.sql 还原。若已上线且出现 URL 问题，先 wp theme activate 原主题，再还原数据库，最后清理缓存。

常见问题

块主题能让经典主题的 PHP 模板继续生效吗？

不能。块主题下 PHP 模板会被忽略，必须映射成 html 模板或通过 functions.php 注册块来输出动态内容。

迁移后菜单不见了怎么办？

菜单数据仍在数据库，确认 theme_location 注册名一致，并在编辑器里把 Navigation 块指向已有菜单即可。

自定义字段在块主题里还能显示吗？

能。用块绑定（Block Bindings）或在 functions.php 注册自定义块读取 get_post_meta()，不要直接依赖经典模板的 the_meta()。

收尾动作清单

• 迁移前导出数据库与固定链接结构，原主题目录保留只读副本。
• 按对照表完成模板映射并在编辑器逐一预览。
• 迁移后 curl 抽查 20 条 URL 并全量回归四层检查。
• 回滚脚本与备份放到可一键执行的位置。

需要团队接手这次迁移，可查看我们的主题开发服务：https://runokwp.com/services/theme-development/。

参考资料与延伸阅读

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