用途:为 Vue 3 提供全栈 <head> 管理,适用于编写、审查或调试使用 @unhead/vue 的代码。版本 3.4.1,仅 ESM,不支持 CJS;对等依赖 vue >= 3.5.18,可选 vite >= 6.4.2、webpack >= 5.0.0。不支持 Vue 2(需用 @unhead/vue@^1);Nuxt 已内置,无需手动安装配置。
主要能力:提供 useHead、useSeoMeta、useHeadSafe、useScript、injectHead 等组合式 API,支持响应式标题与 meta、第三方脚本加载、SSR 与流式 SSR、构建插件与可选插件。
使用方式:必须安装并创建 head 实例后注册为 Vue 插件。客户端从 @unhead/vue/client 导入 createHead,服务端从 @unhead/vue/server 导入。组合式 API 从 @unhead/vue 根导入并在 setup() 内使用。构建插件从 @unhead/vue/bundler 导入 Unhead()。
限制与注意:异步上下文中调用 useHead() 会报错,需用顶层 await、refs/computed 或 injectHead() 解决;禁止在 watcher 回调内调用 useHead();去重键为 key;内联内容用 innerHTML,body 脚本用 tagPosition: 'bodyClose';不可信输入用 useHeadSafe();Vue 中访问 head 实例用 injectHead()。3.4.1 中 useServerHead 等、@unhead/vue/legacy、resolveUnrefHeadInput、unheadVuePlugin、MergeHead 已弃用;v3 移除 DeprecationsPlugin、setHeadInjectionHandler、createHeadCore 等。常见错误包括从根导入 createHead、await renderSSRHead/renderDOMHead、把 useScript() 当 Promise、meta 缺 content、字体预加载缺 crossorigin。