Headless WordPress & FaustJS - 自定义模板解析异常问题

算力阿峰

2026-6-15

排查FaustJS非路由依赖自定义模板不生效问题

针对你遇到的非路由依赖自定义模板无法匹配、始终使用默认page.js的问题，可按以下步骤逐一排查：

核对模板命名与注册一致性
确保WordPress后台页面指定的模板slug（如page-test-template）与FaustJSwp-templates文件夹中的文件名完全一致（包括大小写，比如page-test-template.js/page-test-template.tsx）。同时确认WordPress侧已通过register_page_template正确注册该模板，保证模板slug与GraphQL返回值完全匹配。
检查FaustJS模板配置
查看faust.config.js中的templates路径配置，默认指向wp-templates，若有自定义路径需确保指向正确。另外检查是否自定义了getTemplateName函数，该函数若存在错误逻辑，可能会覆盖GraphQL返回的模板优先级，导致非路由场景下的模板匹配失效。
调试模板匹配过程
在默认page.js中添加日志打印，输出当前传入的templateName参数，确认是否接收到了page-test-template值；也可在页面组件中使用useTemplate钩子，获取当前实际匹配的模板名称，验证是否与GraphQL返回的优先级列表一致。
清理缓存并验证GraphQL查询
清除LocalWP的WordPress缓存、FaustJS前端构建缓存（如.next或node_modules/.cache文件夹），重新构建项目后测试。同时在WordPress的GraphiQL中执行以下查询，确认template字段返回值是否正确：
```
query GetPageDetails($id: ID!) {
  page(id: $id, idType: DATABASE_ID) {
    template
  }
}
```
排查已知Bug
查看FaustJS官方GitHub Issues，搜索类似“non-route template priority”相关问题，确认是否为已报告的版本Bug。若是，可尝试升级至最新版FaustJS，或临时通过自定义getTemplateName函数手动处理模板优先级逻辑。