如何在WordPress主题中正确引入CSS

wp_enqueue_style 必须挂载到 wp_enqueue_scripts 钩子上，不可在 functions.php 顶层或 header.php 中直接调用；handle 需唯一前缀，$src 必须为可访问 URL，$deps 和 $ver 需正确传入数组与字符串/数字。

wp_enqueue_style 必须挂到 wp_enqueue_scripts 钩子上

直接在 functions.php 顶层写 wp_enqueue_style()，PHP 会报 Fatal error: Call to undefined function wp_enqueue_style()——函数根本没加载进来。塞进 header.php 更糟，HTML 已开始输出，再调用会触发 “headers already sent” 错误。

WordPress 只在 wp_enqueue_scripts 这个钩子触发时才准备好资源调度系统，且此时 尚未输出，是唯一安全时机。

1. 必须用 add_action('wp_enqueue_scripts', 'your_function_name') 包裹调用逻辑
2. 子主题不能依赖父主题的钩子自动生效，得在自己的 functions.php 中显式挂载
3. 如果想替换默认样式（比如 twentytwentyfour-style），得先 wp_dequeue_style('twentytwentyfour-style')，再 wp_enqueue_style()

handle 名称重复会导致样式静默失效

你写的 wp_enqueue_style('style', ...) 和插件或父主题里同名的 'style' 冲突时，后注册的那个会彻底覆盖前一个。浏览器里看不到对应 ，也不报错，CSS 就是不生效——这是最常被误判为“代码没运行”的真凶。

检查是否已加载：调用 wp_style_is('mytheme-custom-css', 'enqueued') 返回 true 才表示成功入队。

1. handle 必须加前缀，例如 'mytheme-header-fix'、'childtheme-override'
2. 避免用通用名如 'style'、'main'、'css'
3. 子主题中若需依赖父主题样式，必须显式声明 $deps 数组，不能靠 @import 或手动

$src 参数必须是可访问的 URL，不是服务器路径

传 get_template_directory() . '/style.css' 或 __DIR__ . '/assets/css/main.css' 进去，结果一定是 404。WordPress 不解析服务器路径，它只认浏览器能直接请求的完整 URL。

常见正确写法：

1. 主题根目录 style.css：get_stylesheet_uri()
2. 父主题里的 CSS（子主题中引用）：get_template_directory_uri() . '/assets/css/main.css'
3. 子主题自定义 CSS：get_stylesheet_directory_uri() . '/css/custom.css'
4. 插件内 CSS：plugin_dir_url(__FILE__) . 'css/admin.css'（比 plugins_url() 更稳）

注意：get_stylesheet_directory() 返回的是类似 /var/www/html/wp-content/themes/mychild 的服务器路径，拼进 $src 就废了。

$deps 和 $ver 参数不可省略或传错类型

PHP 8+ 对空值更敏感，传 null 或布尔值容易引发警告；更重要的是，不声明依赖会破坏加载顺序——比如你想让 Bootstrap 在你的主题 CSS 之前加载，但没设 $deps = array('bootstrap')，结果按钮样式全乱。

版本号建议用文件修改时间防缓存：filemtime(get_stylesheet_directory() . '/style.css')，而不是硬写 '1.0'。

1. $deps 必须是数组，哪怕为空也得写 array()，不能省略
2. $ver 必须是字符串或数字，传 false 或 null 在 PHP 8+ 下可能触发 warning
3. $media 默认是 'all'，按需可改为 'screen' 或 'print'

实际开发中最容易被忽略的，是 handle 唯一性和 $src 的 URL 属性——这两个点出错，页面上完全看不出痕迹，调试时得主动查 wp_style_is() 和浏览器 Network 标签页看请求是否 404。