模板继承时 `get_template_part` 的"路径幻觉"：我如何在子主题覆盖与插件回退之间造出一条"双向隧道"

插件开发 27 浏览 0 回复返回上级

上周给一个多站点插件做前端渲染重构，卡在模板加载逻辑上整整两天。需求很简单：插件提供默认模板，允许子主题覆盖，同时支持用户通过后台选项切换"布局模式"。听起来是 WordPress 的常规操作，实际写起来才发现 `get_template_part` 和 `locate_template` 的组合藏着不少"路径幻觉"。

第一坑：插件目录里的模板成了"孤岛"

最初我直接把模板扔在 `templates/` 下，用 `include PLUGIN_DIR . 'templates/card.php'` 硬加载。子主题想覆盖？没门，路径写死了。后来改成：

function myplugin_get_template( $slug, $name = null ) {
    $templates = array();
    if ( isset( $name ) ) {
        $templates[] = "myplugin/{$slug}-{$name}.php";
    }
    $templates[] = "myplugin/{$slug}.php";

    $template = locate_template( $templates );

    if ( ! $template ) {
        $fallback = plugin_dir_path( __FILE__ ) . "templates/{$slug}.php";
        if ( $name && file_exists( plugin_dir_path( __FILE__ ) . "templates/{$slug}-{$name}.php" ) ) {
            $fallback = plugin_dir_path( __FILE__ ) . "templates/{$slug}-{$name}.php";
        }
        $template = $fallback;
    }

    return $template;
}

这里 `locate_template` 会优先在子主题/父主题里找 `myplugin/card-default.php`，找不到才回退插件目录。看起来完美了？直到我在多站点环境下测试，发现子主题覆盖后，模板里用 `get_template_directory_uri()` 拿到的居然是子主题路径，而我想加载的 JS/CSS 还在插件里。

第二坑：静态资源的"身份焦虑"

模板被主题覆盖了，但资源文件没跟着"搬家"。我在插件模板里写：

<script src="<?php echo get_template_directory_uri(); ?>/assets/myplugin-chart.js"></script>

子主题覆盖模板后，这行代码自然失效——子主题根本没有这个文件。更隐蔽的是，有些主题会把 `get_template_directory_uri()` 指向 CDN 或子目录，插件资源的路径假设全被打破。

现在的做法是在模板里强制区分"模板来源"：

function myplugin_template_vars() {
    $is_theme_override = ( false !== strpos( get_page_template(), get_stylesheet_directory() ) );
    
    return array(
        'css_url'   => plugins_url( 'assets/css/', __FILE__ ),
        'js_url'    => plugins_url( 'assets/js/', __FILE__ ),
        'img_url'   => plugins_url( 'assets/img/', __FILE__ ),
        'ajax_url'  => admin_url( 'admin-ajax.php' ),
        'nonce'     => wp_create_nonce( 'myplugin_frontend' ),
        'is_custom' => $is_theme_override,
    );
}

模板开头 `extract( myplugin_template_vars() );`，所有资源路径统一走 `plugins_url()`，和模板是否被覆盖脱钩。子主题开发者想换资源？自己 `wp_dequeue_script` 再 `wp_enqueue_script`，边界清晰。

第三坑：`plugins_url()` 的"入口文件陷阱"

最坑的一次，我把辅助函数拆到 `includes/template-functions.php`，结果 `plugins_url( 'assets/', __FILE__ )` 指向了 `includes/assets/`——因为 `__FILE__` 变了。现在统一在插件主文件里定义常量：

// myplugin.php
define( 'MYPLUGIN_URL', plugin_dir_url( __FILE__ ) );
define( 'MYPLUGIN_PATH', plugin_dir_path( __FILE__ ) );

子文件里直接用常量，杜绝相对路径的"漂移"。

一个还没完全满意的折中

目前我的加载链是这样的：后台选项选择 "layout_mode" → 拼接 `card-{mode}` → `locate_template` 找主题覆盖 → 无则插件回退 → 模板内所有资源硬绑定插件 URL。子主题想深度定制？提供完整的 `myplugin/card-custom.php`，或者走我留的 `myplugin_before_card / myplugin_after_card` 动作钩子。

但有个遗留问题：如果用户用了缓存插件（比如 WP Rocket），`locate_template` 的文件系统检查可能被绕过，导致主题更新了覆盖模板但前端仍走旧缓存。我现在是在版本号变化时 `wp_cache_delete` 整个模板片段缓存，感觉不够优雅。你们怎么处理模板继承层级的缓存失效？