专业架构评估与优化方案：TiHUBB_Schema 与 TSF 的深度融合

评估下 core/schema.php 与SEO插件TSF的融合，首先以templates/page-web-development.php 作为MVP来处理。1、TSF主要管Meta，涉及 application/ld+json的部分如果应用了 TiHUBB_Schema则要把TSF的内容接管，防止页面出现两个 application/ld+json；2、前端模板的application/ld+json数据，我们可能来源模板本身，也可能来自后台，两个场景需要考虑到

专业架构评估与优化方案：TiHUBB_Schema 与 TSF 的深度融合（以 page-web-development.php 为 MVP）

作为 WordPress 主题/插件资深架构师，我对当前 core/schema.php 的设计思路给予肯定：通过队列 + 单一输出 + 拦截 TSF 的方式，是符合企业级可维护性的正确方向。下面给出结构化诊断 + 具体优化方案。

---

一、当前问题诊断（MVP 视角）

1. 重复输出风险（Critical）
   • page-web-development.php 中同时存在：
     • TiHUBB_Schema::add($web_development_schema)
     • 直接 echo ‘<script type=”application/ld+json”>’
   • schema.php 在 wp_footer 又会再输出一次完整的 @graph。
   • 结果：页面会出现 2 个 application/ld+json 脚本，违反 Google 最佳实践，可能触发结构化数据解析警告。
2. TSF 拦截的健壮性
   • 当前 intercept_and_silence_tsf() 使用 the_seo_framework_ld_json_scripts 过滤器是正确的（TSF 核心钩子）。
   • 但优先级 9999 仍可能被其他插件/主题覆盖，且未完全处理 TSF 在 wp_head 直接输出的情况。
3. 数据来源双场景未统一
   • 模板硬编码（当前 page-web-development.php）
   • 后台动态（ACF）（tihubb_register_schema action 中已预留）
   • 需要建立统一注册入口，避免模板和核心逻辑耦合过紧。

---

二、推荐最终架构（MVP 立即可落地）

1. 修改 core/schema.php（核心强化）

PHP

<?php
/**
 * TiHUBB Schema 引擎 v2.0 - 企业级单脚本输出 + TSF 完全接管
 */

if (!defined('ABSPATH')) exit;

class TiHUBB_Schema
{
    private static $schema_queue = [];

    public static function init()
    {
        // 更高优先级拦截 TSF
        add_action('plugins_loaded', [__CLASS__, 'intercept_tsf'], 5);

        // 统一输出（推荐 wp_head 靠前位置，更利于 SEO 爬虫）
        add_action('wp_head', [__CLASS__, 'render'], 99);

        // 注册页面级 Schema（推荐方式）
        add_action('wp', [__CLASS__, 'register_page_schemas']);
    }

    /**
     * 强化 TSF 拦截
     */
    public static function intercept_tsf()
    {
        // 彻底禁用 TSF 原生 JSON-LD 输出
        add_filter('the_seo_framework_ld_json_scripts', '__return_empty_array', 9999);

        // 吸收 TSF 已生成的内容（兼容旧数据）
        add_filter('the_seo_framework_ld_json_scripts', function($scripts) {
            if (empty($scripts)) return $scripts;

            foreach ((array)$scripts as $item) {
                if (is_array($item)) {
                    self::add($item);
                }
            }
            return [];
        }, 9998);
    }

    /**
     * 统一注册入口
     */
    public static function register_page_schemas()
    {
        if (!is_page_template('templates/page-web-development.php')) {
            return;
        }

        // 触发自定义 action，允许 ACF 或其他逻辑注册
        do_action('tihubb_register_schema');
    }

    public static function add($data)
    {
        if (empty($data) || !is_array($data)) return;

        // 清理多余 context
        if (isset($data['@context'])) {
            unset($data['@context']);
        }

        // 防重复 @id
        $id = $data['@id'] ?? null;
        if ($id) {
            foreach (self::$schema_queue as $existing) {
                if (($existing['@id'] ?? null) === $id) {
                    return;
                }
            }
        }

        self::$schema_queue[] = $data;
    }

    /**
     * 单一输出 - 推荐放在 wp_head
     */
    public static function render()
    {
        if (is_admin() || empty(self::$schema_queue)) return;

        $final_schema = [
            '@context' => 'https://schema.org',
            '@graph'   => self::$schema_queue
        ];

        echo "\n<!-- TiHUBB Schema Engine -->\n";
        echo '<script type="application/ld+json" class="tihubb-schema-graph">';
        echo wp_json_encode($final_schema, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        echo "</script>\n";
    }
}

TiHUBB_Schema::init();

---

2. 优化 templates/page-web-development.php

关键修改：移除直接输出，只负责数据注册

PHP

<?php
// ... 头部保持不变

$web_development_faqs = [ /* ... */ ];

// 构建 Schema（推荐结构）
$web_development_schema = [
    '@type'       => 'Service',
    '@id'         => trailingslashit(get_permalink()) . '#web-development-service',
    'name'        => '网站建设与 WordPress 定制开发服务',
    // ... 其他字段
];

$faq_schema = [
    '@type'      => 'FAQPage',
    '@id'        => trailingslashit(get_permalink()) . '#web-development-faq',
    'mainEntity' => array_map(/* ... */ , $web_development_faqs),
];

// 统一注册（不再直接 echo）
TiHUBB_Schema::add($web_development_schema);
TiHUBB_Schema::add($faq_schema);

// 删除原来的 <script type="application/ld+json"> 块！！！

get_header();

---

3. 动态 ACF 场景支持（推荐）

在 tihubb_register_schema action 中完善：

PHP

add_action('tihubb_register_schema', function() {
    if (!is_page_template('templates/page-web-development.php')) return;

    // ACF 动态 FAQ 示例
    $faqs = get_field('faq_items'); // Repeater 字段
    if ($faqs) {
        $mainEntity = [];
        foreach ($faqs as $faq) {
            $mainEntity[] = [
                '@type'          => 'Question',
                'name'           => $faq['question'],
                'acceptedAnswer' => ['@type' => 'Answer', 'text' => $faq['answer']],
            ];
        }

        TiHUBB_Schema::add([
            '@type'      => 'FAQPage',
            '@id'        => trailingslashit(get_permalink()) . '#faq',
            'mainEntity' => $mainEntity,
        ]);
    }

    // Service Schema 可从 ACF 读取标题、描述等
});

---

三、架构总结与后续演进建议

当前 MVP 优化优先级：

1. 立即执行：移除模板中的直接 <script> 输出 + 升级 schema.php。
2. 测试验证：使用 Google Rich Results Test + Schema Markup Validator。
3. 监控：确保 TSF 的 Organization / WebSite 等全局 Schema 被成功吸收。

长期演进方向：

• 将 Schema 注册做成 TiHUBB_Schema_Registry 单例，支持按模板/CPT 自动加载。
• 支持 BreadcrumbList、WebPage、Organization 等全局节点自动合并。
• 增加缓存层（Transient），避免高并发下重复构建。
• 考虑与 Rank Math / Yoast 的兼容拦截策略（类似 TSF 处理）。