WordPress ACF模板如何复用公共代码并正确传递变量

你之前用get_template_part、普通include、include(locate_template())三种方式引入抽离逻辑不生效，核心不是路径错误，是变量作用域不匹配：

• WordPress的模板片段引入默认不会自动继承父模板内定义的局部变量，你抽离到links.php里的代码如果直接调用父模板里赋值的$link、$link_url等变量，会因为作用域隔离拿不到值，逻辑自然跑不通
• 普通include如果写在函数、循环回调等内部作用域中，也会出现变量读取异常的问题
• 这个问题和ACF插件本身无关，是WordPress模板复用的通用机制问题

两种生产环境常用的方案，按需选择即可：

方案1：模板片段+显式传参（改动成本最低） #

WordPress 5.5及以上版本的get_template_part原生支持第三个参数传值，不需要改现有逻辑结构，只要调整传参方式即可：

1. 调整你的links.php片段逻辑，统一从$args数组读取传入参数，不要直接依赖父模板变量，示例代码：

<?php
// 入参校验，参数缺失直接终止渲染
if (empty($args['link_data']) || !is_array($args['link_data'])) {
    return;
}
$link = $args['link_data'];

// 这里保留你原来写的URL标识符校验、options值替换逻辑
$match_flag = '你的自定义URL匹配标识';
if (str_contains($link['url'], $match_flag)) {
    $link_url = get_field('your_option_url', 'option');
    $link_title = get_field('your_option_title', 'option');
    $link_target = get_field('your_option_target', 'option');
} else {
    $link_url = $link['url'];
    $link_title = $link['title'];
    $link_target = $link['target'] ?: '_self';
}
?>
<a href="<?php echo esc_url($link_url); ?>" target="<?php echo esc_attr($link_target); ?>">
    <?php echo esc_html($link_title); ?>
</a>

2. 所有需要渲染链接的模板位置，获取ACF字段后显式传参引入片段即可：

<?php
$custom_link = get_field('custom_link');
get_template_part('links', null, [
    'link_data' => $custom_link
]);
?>

如果你用的是5.5以下的老旧WordPress版本，需要在调用get_template_part前执行set_query_var('link_data', $custom_link)挂载变量，片段内直接读取$link_data即可，建议优先升级核心版本。

方案2：封装全局函数（稳定性最高，无作用域问题） #

如果要彻底规避模板引入的作用域、路径问题，最稳妥的方式是把链接处理逻辑封装成全局函数，放到主题的functions.php文件中，所有位置可以直接调用：

1. 在functions.php中添加渲染函数：

<?php
/**
 * 渲染带全局替换规则的ACF链接
 * @param array $acf_link ACF链接字段返回的数组格式值
 * @return void 直接输出转义后的安全a标签
 */
function render_custom_acf_link($acf_link) {
    if (empty($acf_link) || !is_array($acf_link)) {
        return;
    }

    // 保留你原有的URL匹配、options替换逻辑
    $match_flag = '你的自定义URL匹配标识';
    if (str_contains($acf_link['url'], $match_flag)) {
        $link_url = get_field('your_option_url', 'option');
        $link_title = get_field('your_option_title', 'option');
        $link_target = get_field('your_option_target', 'option');
    } else {
        $link_url = $acf_link['url'];
        $link_title = $acf_link['title'];
        $link_target = $acf_link['target'] ?: '_self';
    }

    printf(
        '<a href="%s" target="%s">%s</a>',
        esc_url($link_url),
        esc_attr($link_target),
        esc_html($link_title)
    );
}
?>

2. 任意模板中需要渲染链接时，直接传参调用函数即可，不需要额外引入文件：

<?php
$custom_link = get_field('custom_link');
render_custom_acf_link($custom_link);
?>

• 抽离复用逻辑时，永远不要依赖父作用域的隐式变量，所有需要的值必须显式传入，避免不同页面、不同位置调用时出现变量缺失问题
• 提前确认ACF链接字段的返回值设置为「数组」格式，如果返回字符串类型，数组取值逻辑会直接报错
• 前端输出的所有动态值必须保留esc_url、esc_attr、esc_html转义逻辑，避免XSS风险
• 如果坚持用include方式引入文件，必须用get_theme_file_path()获取文件绝对路径，不要写相对路径，正确写法为include get_theme_file_path('links.php');，引入前同样要注意显式传参。

内容的提问来源于stack exchange，提问作者Daniil Kochetkov