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

结论先行

经典主题迁移块主题的正确路径是保留数据层（菜单、自定义字段、固定链接）不动，只把 PHP 模板逐文件映射为 html 模板并用 theme.json 接管样式，迁移后以 URL 与内容结构不变作为通过标准，任何一条不一致就整站回滚。

这条路径的关键在于”数据层不动”。菜单、字段、链接结构都存在数据库里，与主题无关；真正要搬的只有表现层。把这两层分开，迁移就变成一件可控的事；混在一起做，就会出现”菜单丢了、字段没了”这类看似玄学其实必然的事故。

先判断：这次迁移值不值得做

情况	建议	原因
站点要长期运营，编辑希望自己改版式	值得迁	站点编辑器的可视化能力是长期收益
主题已停更、与新版本 WordPress 有兼容告警	值得迁	安全风险与维护成本逐年上升
站点依赖大量 PHP 动态逻辑	谨慎	条件输出需要改写成块或短代码，工作量被低估
页面数量少且短期内会整体改版	不急	不如等到改版时一次性做，避免迁两次

判断的核心是”迁移收益能不能覆盖迁移风险”。纯展示型企业站通常值得；逻辑密集的站点要先盘点动态部分占多少，再决定。

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

迁移前先冻结当前环境：记录 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 声明会导致样式不生效。

theme.json 怎么接管样式

theme.json 是块主题的样式中枢，迁移时按三块搬：

• 变量：把散落在 CSS 里的颜色、字号、间距抽成调色板与排版预设，命名与业务含义对应。
• 全局样式：body 背景、链接色、内容宽度，写在 styles 节点下。
• 块级默认样式：按钮、引用、表格等常用块的默认外观，逐块定义，避免编辑每次手动调。

搬完的判断标准是：新建一个页面，只拖块不加自定义 CSS，出来的效果就应该接近原站。做不到说明变量没抽干净，后期改版还会回到”改一处动上百处”的老问题。

菜单与 widget 迁移

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

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

然后用 Navigation 块在 parts/header.html 中引用已有菜单。widget 区域在块主题里没有直接对应物，常见做法有三种：改建为模板部件、改成区块样板、或直接把内容写进页面。选择依据是这块内容是否需要每页不同。

自定义字段怎么在块主题里显示

能显示，但方式变了。三条路径按推荐度排序：

1. 块绑定（Block Bindings）：把字段值绑定到块属性上，编辑可以在编辑器里直接看到，维护成本最低。
2. 自定义块：在插件里注册一个块，读取 get_post_meta() 输出，适合结构固定的字段组。
3. 短代码：兼容旧内容的过渡方案，编辑体验最差，不建议长期依赖。

不要做的事：把字段输出逻辑写进主题模板文件。块主题下模板是 HTML，写不进去，硬塞会导致编辑器与前台不一致。相关的数据结构注册位置可参考 自定义文章类型与分类法该怎么设计（附常见设计错误）。

避免 URL 变动

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

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

固定链接结构保持 /%postname%/ 或原有结构不变；如果经典主题注册过自定义文章类型的 rewrite slug，必须在块主题的 functions.php 中原样保留，改造前先读一遍现有注册代码。

分阶段迁移：把风险切成小块

1. 第一阶段：搭骨架。建 templates 与 parts，先让首页与文章页在块主题下跑起来。
2. 第二阶段：迁菜单与 widget，确认导航与侧栏内容齐全。
3. 第三阶段：迁样式到 theme.json，逐页比对视觉差异。
4. 第四阶段：处理自定义字段与条件逻辑，补齐动态部分。
5. 第五阶段：全站回归，抽查 20 条 URL，确认 URL 与内容结构不变。

每阶段结束都在预发布环境验收一次，不通过就不进下一阶段。一次性全量迁移最容易出现”问题太多无法定位”的情况。

迁移后回归检查

回归检查要覆盖四层：内容、模板、交互、性能。内容层核对文章数量、分类计数、菜单项数量；模板层逐页打开截图比对；交互层测试搜索、分页、评论提交；性能层用 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()，不要直接依赖经典模板里的输出语句。

可以先迁一部分页面吗？

可以，而且推荐。先迁流量占比低的栏目，跑通菜单、字段与 URL 三件事后再扩大范围，避免一次性切换带来的排查困难。

老站点没有精力迁，能继续用经典主题吗？

短期内可以，WordPress 仍然支持经典主题。但要注意主题是否还在维护、与当前核心版本有无兼容告警。若已停更，安全风险会随时间上升，建议至少排一次迁移评估。

收尾动作清单

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

需要团队接手这次迁移，可查看我们的 主题开发服务。

参考资料与延伸阅读

• 区块编辑器手册
• WordPress 主题开发手册
• WordPress 插件开发手册