各位观众老爷，晚上好！今天咱们来聊聊 WordPress 里一个看似简单，实则暗藏玄机的函数：get_theme_file_uri()。 咱们要像剥洋葱一样，一层一层地揭开它的面纱，看看它究竟是如何获取主题文件的 URL，又是如何巧妙地支持子主题的。
一、初识 get_theme_file_uri()：它的作用是什么？
简单来说，get_theme_file_uri() 的作用就是获取主题目录下指定文件的 URL。这听起来很简单，但它比直接拼接路径要聪明得多。 它会考虑到以下情况：
- 父主题与子主题： 当使用子主题时，它会优先查找子主题目录下是否存在该文件，如果不存在，才会去父主题目录下查找。
- 缓存： 为了提高性能，它会利用 WordPress 的缓存机制。
- 主题切换： 当主题切换时，它能正确地返回当前主题的文件 URL。
二、从源码入手：get_theme_file_uri() 的内部结构
让我们深入 wp-includes/theme.php 文件，看看 get_theme_file_uri() 的庐山真面目。
function get_theme_file_uri( $file = '' ) {
$file = ltrim( $file, '/' );
if ( empty( $file ) ) {
$url = get_stylesheet_directory_uri();
} else {
$url = get_stylesheet_directory_uri() . '/' . $file;
}
/**
* Filters the URL to a file in the theme.
*
* @since 4.7.0
*
* @param string $url The complete URL to the file including scheme and path.
* @param string $file Relative path to the file.
*/
return apply_filters( 'theme_file_uri', $url, $file );
}看起来代码量不多，但这里面却包含了几个关键点：
ltrim( $file, '/' )： 移除文件路径开头的斜杠，确保路径的规范性。get_stylesheet_directory_uri()： 这是获取主题目录 URI 的关键函数，后面我们会重点分析它。apply_filters( 'theme_file_uri', $url, $file )： 这是一个钩子（Filter Hook），允许我们通过插件或主题修改最终的 URL。
三、get_stylesheet_directory_uri()：寻找主题目录的 URI
get_stylesheet_directory_uri() 函数才是真正决定是使用父主题还是子主题的关键。 让我们继续追踪它的源码。
function get_stylesheet_directory_uri() {
/**
* Filters the stylesheet directory URI.
*
* @since 1.5.0
*
* @param string $stylesheet_dir_uri Stylesheet directory URI.
* @param string $stylesheet Stylesheet name.
*/
return apply_filters( 'stylesheet_directory_uri', get_stylesheet_directory_uri_raw(), get_stylesheet() );
}又是一个 Filter Hook！ WordPress 真是把扩展性发挥到了极致。 真正的逻辑其实在 get_stylesheet_directory_uri_raw() 函数中。
function get_stylesheet_directory_uri_raw() {
$stylesheet = get_stylesheet();
$theme = wp_get_theme( $stylesheet );
if ( ! $theme->exists() ) {
return false;
}
return $theme->get_stylesheet_directory_uri();
}这里发生了什么？
get_stylesheet()： 获取当前使用的样式表（Stylesheet）的名称。 如果是子主题，这里会返回子主题的名称； 如果是父主题，则返回父主题的名称。wp_get_theme( $stylesheet )： 根据样式表名称获取主题对象。 这个主题对象包含了主题的各种信息，比如主题目录、主题名称等等。$theme->get_stylesheet_directory_uri()： 从主题对象中获取样式表目录的 URI。
敲黑板！重点来了：
- 如果当前使用的是子主题，
get_stylesheet()会返回子主题的名称，wp_get_theme()会获取子主题的对象，最终返回子主题的目录 URI。 - 如果当前使用的是父主题，
get_stylesheet()会返回父主题的名称，wp_get_theme()会获取父主题的对象，最终返回父主题的目录 URI。
四、子主题的优先级：get_template_directory_uri() 的角色
你可能会问，如果子主题和父主题都有同名文件，get_theme_file_uri() 如何决定使用哪个？ 答案就在 get_stylesheet_directory_uri() 的选择上。
get_stylesheet_directory_uri() 总是返回当前使用的样式表（也就是子主题，如果存在）的目录 URI。 如果文件存在于子主题目录中，那么 get_theme_file_uri() 就会返回子主题的文件 URL。
但是，如果文件不存在于子主题目录中，但存在于父主题目录中呢？ 这时候就需要 get_template_directory_uri() 函数。
function get_template_directory_uri() {
/**
* Filters the template directory URI.
*
* @since 1.5.0
*
* @param string $template_dir_uri Template directory URI.
* @param string $template Template name.
*/
return apply_filters( 'template_directory_uri', get_template_directory_uri_raw(), get_template() );
}
function get_template_directory_uri_raw() {
$template = get_template();
$theme = wp_get_theme( $template );
if ( ! $theme->exists() ) {
return false;
}
return $theme->get_template_directory_uri();
}get_template_directory_uri() 的逻辑与 get_stylesheet_directory_uri() 非常相似，区别在于它使用的是 get_template() 函数来获取模板名称，而不是 get_stylesheet()。
get_template() 函数总是返回父主题的名称。 因此，get_template_directory_uri() 总是返回父主题的目录 URI。
总结一下：
get_stylesheet_directory_uri()： 返回当前使用的样式表（子主题或父主题）的目录 URI。get_template_directory_uri()： 总是返回父主题的目录 URI。
get_theme_file_uri() 默认只使用 get_stylesheet_directory_uri()。 如果你想在子主题找不到文件时，退回到父主题查找，你需要使用 get_template_directory_uri()。 后面我们会演示如何结合这两个函数来实现更灵活的文件查找。
五、实战演练：代码示例与应用场景
说了这么多理论，不如来点实际的。 让我们看几个代码示例，演示 get_theme_file_uri() 的用法。
示例 1：获取主题目录下 style.css 的 URL
$style_url = get_theme_file_uri( 'style.css' );
echo $style_url; // 输出：http://example.com/wp-content/themes/my-theme/style.css (或子主题的 URL)如果当前使用的是子主题，并且子主题目录下存在 style.css 文件，那么 $style_url 就会是子主题的 URL。 否则，它会是父主题的 URL。
示例 2：获取主题目录下 assets/js/main.js 的 URL
$script_url = get_theme_file_uri( 'assets/js/main.js' );
echo $script_url; // 输出：http://example.com/wp-content/themes/my-theme/assets/js/main.js与示例 1 类似，get_theme_file_uri() 会优先查找子主题目录下是否存在该文件。
示例 3：结合 get_stylesheet_directory_uri() 和 get_template_directory_uri() 实现更灵活的文件查找
假设你想优先使用子主题的 custom.js 文件，如果子主题没有，则使用父主题的 custom.js 文件。 你可以这样做：
$child_theme_script_url = get_theme_file_uri( 'assets/js/custom.js' );
$parent_theme_script_url = get_template_directory_uri() . '/assets/js/custom.js';
if ( file_exists( get_stylesheet_directory() . '/assets/js/custom.js' ) ) {
$script_url = $child_theme_script_url;
} elseif ( file_exists( get_template_directory() . '/assets/js/custom.js' ) ) {
$script_url = $parent_theme_script_url;
} else {
$script_url = ''; // 文件不存在
}
if ( ! empty( $script_url ) ) {
echo '<script src="' . esc_url( $script_url ) . '"></script>';
}这段代码首先尝试获取子主题的 custom.js URL，然后使用 file_exists() 函数检查子主题目录下是否存在该文件。 如果存在，则使用子主题的 URL； 否则，检查父主题目录下是否存在该文件，如果存在，则使用父主题的 URL； 如果都不存在，则将 $script_url 设置为空。
六、使用 Filter Hook：定制 get_theme_file_uri() 的行为
还记得 get_theme_file_uri() 函数中的 apply_filters( 'theme_file_uri', $url, $file ) 吗？ 我们可以使用这个 Filter Hook 来定制 get_theme_file_uri() 的行为。
例如，假设你想将所有主题文件的 URL 都指向 CDN，你可以这样做：
function my_theme_file_uri( $url, $file ) {
$cdn_url = 'https://cdn.example.com/wp-content/themes/' . get_stylesheet();
return str_replace( get_stylesheet_directory_uri(), $cdn_url, $url );
}
add_filter( 'theme_file_uri', 'my_theme_file_uri', 10, 2 );这段代码会将所有主题文件的 URL 中的主题目录 URI 替换为 CDN 的 URL。
七、注意事项与最佳实践
- 使用
esc_url()函数： 在输出 URL 时，一定要使用esc_url()函数进行转义，以防止 XSS 攻击。 - 避免硬编码路径： 尽量使用
get_theme_file_uri()或get_template_directory_uri()函数来获取文件 URL，而不是硬编码路径。 这样可以确保代码的兼容性和可维护性。 - 利用缓存：
get_theme_file_uri()函数内部已经使用了 WordPress 的缓存机制，所以你无需手动进行缓存。 - 了解主题结构： 熟悉主题的文件结构，可以帮助你更好地使用
get_theme_file_uri()函数。
八、总结与展望
今天我们深入探讨了 WordPress 的 get_theme_file_uri() 函数，了解了它的作用、内部结构、以及如何结合 get_stylesheet_directory_uri() 和 get_template_directory_uri() 来实现更灵活的文件查找。 我们还学习了如何使用 Filter Hook 来定制 get_theme_file_uri() 的行为。
希望今天的讲座能帮助你更好地理解 WordPress 的主题机制，并在实际开发中更加灵活地使用 get_theme_file_uri() 函数。 记住，理解源码是提升编程技能的关键！
最后，送大家一句话： “代码虐我千百遍，我待代码如初恋。” 咱们下期再见！