unhead-vue-skilld

@unhead/vue 3.4.1

适用于 Vue 3 的全栈 <head> 管理。仅支持 ESM（"type": "module"），不支持 CJS。 Peer 依赖：vue >= 3.5.18；可选依赖：vite >= 6.4.2、webpack >= 5.0.0（来源：package.json:138-150）。 Vue 2：不支持；请使用 @unhead/vue@^1。 Nuxt：已集成 Unhead；请勿手动安装或配置。

设置（必需）

安装 @unhead/vue，创建 head 实例，并将其注册为 Vue 插件。createHead 来自子路径导出，而非包根目录。

// entry-client.ts (SPA or hydration)
import { createHead } from '@unhead/vue/client'
import { createApp } from './main'

const { app } = createApp()
const head = createHead()
app.use(head)
app.mount('#app')

// entry-server.ts (SSR)
import { createHead } from '@unhead/vue/server'
import { renderToString } from 'vue/server-renderer'
import { createApp } from './main'

export async function render(url: string) {
  const { app } = createApp()
  const head = createHead()
  app.use(head)
  const html = await renderToString(app)
  return { html, head } // render tags later with transformHtmlTemplate(head, template)
}

完整的 SSR 模板接线、流式 SSR、Options API 和自动导入：references/setup.md。

组合式函数

全部从 @unhead/vue 根目录导入，并在 setup() 中使用：

<script setup lang="ts">
import { useHead, useSeoMeta } from '@unhead/vue'

useHead({
  title: () => `${user.value.name} - Profile`, // getters, refs, computed all reactive
  titleTemplate: '%s | My Site',
  meta: [{ name: 'description', content: () => description.value }],
})

useSeoMeta({ // flat, type-safe keys; og/twitter handled automatically
  ogTitle: 'My Page',
  ogImage: 'https://example.com/image.jpg',
})
</script>

// Third-party scripts
import { useScript } from '@unhead/vue'

const { proxy, onLoaded, status } = useScript(
  { src: 'https://example.com/analytics.js' },
  { use: () => window.analytics, trigger: 'client' },
)
proxy.track('pageview') // queued until the script loads

详情、选项表和用法示例：references/composables.md。

重要规则

1. 异步上下文：在 onMounted()/侦听器中 await 之后调用 useHead() 会抛出 useHead() was called without provide context。按以下优先顺序修复：在 <script setup> 中使用顶层 await；使用 refs/computed 声明一次 useHead()，之后更新 ref；在 setup 时捕获 const head = injectHead()，并传入 useHead(input, { head })。来源：https://unhead.unjs.io/docs/vue/head/guides/core-concepts/reactivity-and-context
2. 切勿在侦听器回调中调用 useHead()：每次调用都会新增一个条目并造成标签重复。请将响应式值传入一次 useHead() 调用。
3. 去重键是 key，而不是 hid/vmid：meta: [{ key: 'description', name: 'description', content: '...' }]。
4. 内联内容：使用 innerHTML（v1 中为 children）；body 脚本使用 tagPosition: 'bodyClose'（以前是 body: true）。
5. 不可信输入：使用 useHeadSafe()；它会将属性限制在白名单内，并移除脚本/事件处理程序。
6. 在 Vue 中访问 head 实例：使用 @unhead/vue 中的 injectHead()，而不是 unhead 中的 getActiveHead()；只有前者会绑定到组件上下文（例如 onServerPrefetch）。

3.4.1 中已弃用（仍存在，但计划移除）

导出项	状态	替代项
useServerHead、useServerHeadSafe、useServerSeoMeta	已弃用（dist/index.d.ts:26-30）	useHead / useHeadSafe / useSeoMeta
@unhead/vue/legacy（createHead、createServerHead、legacyPlugins）	已弃用，将在 v4 中移除（dist/legacy.d.ts:14-30）	@unhead/vue/client / @unhead/vue/server
resolveUnrefHeadInput	已弃用（dist/utils.d.ts:9）	unhead/utils 中的 resolveTags(head)
@unhead/vue/stream/vite 中的 unheadVuePlugin	已弃用（dist/stream/vite.d.ts:8）	@unhead/vue/bundler 中的 Unhead({ streaming: true }).vite()
MergeHead 类型	已弃用（dist/types.d.ts:66）	VueHeadClient 上的泛型

v3 中已移除（无法编译）：DeprecationsPlugin、setHeadInjectionHandler、createHeadCore、{ mode: 'server' | 'client' } 条目选项、init/dom:renderTag/dom:rendered 钩子、headEntries()（请使用 [...head.entries.values()]）。 迁移详情：references/migration.md。

导出映射

子路径	用途
@unhead/vue	组合式函数：useHead、useSeoMeta、useHeadSafe、useScript、injectHead、VueHeadMixin、unheadVueComposablesImports、createUnhead、defineLink、defineScript
@unhead/vue/client	createHead()（SPA/水合）、renderDOMHead、VueHeadMixin
@unhead/vue/server	createHead()（SSR）、renderSSRHead、transformHtmlTemplate、propsToString
@unhead/vue/components	<Head> 组件
@unhead/vue/plugins	重新导出 unhead/plugins（TemplateParamsPlugin、AliasSortingPlugin、PromisePlugin、InferSeoMetaPlugin、ValidatePlugin 等）
@unhead/vue/bundler	适用于 vite/webpack/rspack/rollup 的统一构建插件 Unhead()
@unhead/vue/vite	仅适用于 Vite 的 Unhead()；建议使用 /bundler
@unhead/vue/stream/server、/stream/client	用于流式 SSR 的 createStreamableHead()
@unhead/vue/types、/utils、/scripts、/legacy	类型、工具、脚本类型、旧版兼容层

签名和完整类型接口：references/api-surface.md。

创建时使用可选插件

模板参数（%s、%separator）、别名排序（before:/after:）和 Promise 输入自 v2 起均为可选项：

import { createHead } from '@unhead/vue/client'
import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'

const head = createHead({ plugins: [TemplateParamsPlugin, AliasSortingPlugin] })

如果没有 TemplateParamsPlugin，%siteName 占位符会按原样显示。

构建插件（推荐用于独立 Vue 应用）

// vite.config.ts
import { Unhead } from '@unhead/vue/bundler'

export default defineConfig({
  plugins: [vue(), Unhead()], // add { streaming: true } for streaming SSR
})

从客户端构建包中移除仅供服务端使用的组合式函数，将 useSeoMeta() 转换为 useHead()（约 3kb），并在开发环境中注入 ValidatePlugin。选项表和 webpack 说明：references/build-plugins.md。

常见错误

• 从 @unhead/vue 根路径导入 createHead（v2 中已移除）：请使用 /client 或 /server。
• 对 renderSSRHead / renderDOMHead 使用 await：两者在 v3 中均为同步函数。
• useScript() 的返回值不是 Promise：请使用 onLoaded(() => ...)；通过 .proxy 调用 API。
• Meta 标签需要 content：{ name: 'description', content: null } 会移除该标签。
• 字体预加载需要 crossorigin：{ rel: 'preload', as: 'font', href: '/f.woff2', crossorigin: 'anonymous' }。

参考资料

• references/setup.md — SPA、SSR、流式 SSR、Options API、<Head> 组件、自动导入、默认值
• references/composables.md — useHead、useSeoMeta、useHeadSafe、useScript 的用法和选项
• references/api-surface.md — 导出映射、类型、实例 API
• references/build-plugins.md — Unhead() 打包工具插件和流式处理
• references/migration.md — v2 和 v3 的重大变更