wp_enqueue_style 必须挂到 wp_enqueue_scripts 钩子上，否则因函数未定义或 headers already sent 报错；$handle 需唯一加前缀，$src 必须为可访问 URL，$deps 和 $ver 不可省略且类型需正确。
wp_enqueue_style 必须挂到 wp_enqueue_scripts 钩子上，否则函数未定义或报 “headers already sent” —— 这不是代码写错了，是根本没进 WordPress 的资源调度流程。
为什么直接在 functions.php 顶层调用会失败
WordPress 只在 wp_enqueue_scripts 钩子触发时才加载并定义 wp_enqueue_style() 函数。在 functions.php 文件最外层（即 PHP 解析阶段）就调用它，PHP 会直接报错：Fatal error: Call to undefined function wp_enqueue_style()。
常见误操作包括：
- 把
wp_enqueue_style('my-css', ...)直接写在functions.php开头或结尾，没包函数、没挂钩子 - 在
header.php或其他模板文件里调用，此时<head>已部分输出，PHP 报 “headers already sent” - 误挂到
init、wp_head等钩子上，前者太早，后者太晚
✅ 正确做法只有一种：
function mytheme_enqueue_custom_css() {<br> wp_enqueue_style(<br> 'mytheme-main-css',<br> get_template_directory_uri() . '/assets/css/main.css',<br> array(),<br> filemtime(get_template_directory() . '/assets/css/main.css')<br> );<br>}<br>add_action('wp_enqueue_scripts', 'mytheme_enqueue_custom_css');
handle 重复会导致样式静默失效
$handle 是全局唯一标识符，不是随便起的别名。两个插件、父主题和子主题、甚至你自己多次注册用了同一个 $handle（比如都叫 'style' 或 'bootstrap'），后注册的会彻底覆盖前一个 —— 浏览器里看不到对应 <link> 标签，控制台无报错，CSS 就是不生效。
立即学习“前端免费学习笔记（深入）”；
排查与规避建议：
🎯 HR面试评价助手（Word版格式） 生成可直接复制到Word文档的标准格式HR面试评价 【使用方式】 1. 发送口令：HR面试评价 2. 粘贴JD文字 3. 上传简历文档 4. 上传面试记录（可选） 5. 复制生成的评价到Word 【输出特点】 - 纯文本格式，可直接粘贴到Word - 层次清晰，标题加粗...
- 给
$handle加主题/插件前缀，例如'mytheme-header-fix'、'pluginname-admin-css' - 用
wp_style_is('mytheme-main-css', 'enqueued')检查是否已被加载 - 如需替换默认样式（如
'twentytwentyfour-style'），先wp_dequeue_style('twentytwentyfour-style')，再wp_enqueue_style()
$src 必须是 URL，不是服务器路径
$src 参数必须是浏览器能直接请求的完整 URL，例如 https://yoursite.com/wp-content/themes/mytheme/assets/css/main.css。传入服务器路径（如 /var/www/html/wp-content/...）或相对路径（如 ./css/main.css）会导致 404。
常见错误写法与修正：
- ❌
get_template_directory() . '/style.css'→get_template_directory()返回的是服务器绝对路径 - ✅ 主题根目录
style.css：用get_stylesheet_uri() - ✅ 父主题 CSS（子主题中引用）：用
get_template_directory_uri() . '/assets/css/main.css' - ✅ 子主题自定义 CSS：用
get_stylesheet_directory_uri() . '/css/custom.css' - ✅ 插件内 CSS：优先用
plugin_dir_url(__FILE__) . 'css/admin.css'，比plugins_url()更稳
依赖和版本参数不能省略
$deps 和 $ver 在 PHP 8+ 下若省略或类型错误（如传 null 或数字），会触发 warning；更重要的是，它们影响加载顺序与缓存控制。
关键规则：
-
$deps必须是数组，哪怕无依赖也要写array()，不能留空或传false -
$ver推荐用文件修改时间：filemtime(get_template_directory() . '/assets/css/main.css')，避免手动维护版本号 - 若 CSS 依赖 Bootstrap 或 FontAwesome，把对应
$handle（如'bootstrap-css'）写进$deps数组，确保它们先加载
子主题若要继承父主题样式，不能靠自动，必须显式声明依赖：wp_enqueue_style('child-theme-css', ..., array('parent-theme-css')) —— 这点极易被忽略，导致子主题样式加载时机错乱或覆盖失败。
