@vueuse/head

VueUse 是一个基于 Vue Composition API 的开源实用工具函数集合库，常被称作“Vue 组合式 API 的瑞士军刀”。它由 Vue 生态核心贡献者维护，为 Vue 2.7+ / Vue 3 项目提供了 200+ 开箱即用的响应式函数，用于解决开发中高频遇到的浏览器 API、DOM 操作、状态管理等重复逻辑。

@vueuse/head 是 VueUse 生态中专门用于管理 HTML <head> 标签的组合式 API 工具库，底层基于 Unhead 实现，主要解决 Vue SPA（单页应用）中动态管理 title、meta、link、script 等文档头信息的痛点。

安装:

npm install @vueuse/head
# 或
yarn add @vueuse/head

主要功能

useHead({
    title: '页面标题',           // 设置 <title>
    meta: [...],                 // 设置 <meta> 标签
    link: [...],                 // 设置 <link> 标签
    script: [...],               // 设置 <script> 标签
    style: [...],                // 设置 <style> 标签
    base: {...},                 // 设置 <base> 标签
    htmlAttrs: {...},            // 设置 <html> 属性
    bodyAttrs: {...}             // 设置 <body> 属性
});

常用示例

1. 设置页面标题

useHead({
    title: 'SofTool.CN'
});
// 结果：<title>SofTool.CN</title>

2. 设置 Meta 标签

useHead({
    meta: [
        { name: 'description', content: 'Free random name picker' },
        { name: 'keywords', content: 'names, random' },
        { property: 'og:title', content: 'SofTool.CN' }
    ]
});

3. 动态标题（使用 computed）

const route = useRoute();

useHead({
    title: computed(() => {
        if (route.path === '/faq') return 'FAQ';
        if (route.path === '/about') return 'About Us';
        return 'SofTool.CN';
    })
});

4. 添加外部脚本和样式

useHead({
    script: [
        {
            src: 'https://SofTool.CN/analytics.js',
            async: true
        }
    ],
    link: [
        {
            rel: 'stylesheet',
            href: 'https://SofTool.CN/style.css'
        }
    ]
});

优势

特性 说明
响应式 使用 computed 或 ref，标题自动更新
SSR 兼容 服务端渲染时也能正常工作
自动去重 相同的标签不会重复添加
生命周期绑定 组件卸载时自动清理

注意事项

  1. 必须在 setup 中调用：因为内部使用了 inject
  2. title 必须是字符串：传入对象会导致 [object Object]
  3. 可以多次调用：后面的调用会合并或覆盖前面的

你遇到的问题

// ❌ 错误：title 传入了对象
useHead({
    title: { name: 'Home' }  // 变成 [object Object]
});

// ✅ 正确：title 必须是字符串
useHead({
    title: 'Home'  // 正常显示
});

总结： useHead 是管理页面 <head> 标签的利器，但要注意 title 必须是字符串，且必须在组件的 setup 中调用。

现状与迁移提醒（重要）

@vueuse/head 目前已进入 Sunset（日落）阶段，官方不再添加新特性，核心功能已迁移并增强为跨框架的 @unhead/vue（Nuxt 核心也在用）。两者 API 几乎完全一致，迁移通常只需改包名导入。

这也是遇到 Failed to resolve import "@vueuse/head" 的原因之一——新项目若未显式安装它就会报错；而对于工具文件（如 adManager.js），如前所述，用原生 document.head.appendChild 往往比引入这个库更轻量。

如果当前项目不是 Nuxt 且没有 SSR 需求，可以继续用 @vueuse/head 或原生 DOM 操作；如果涉及 SSR 或长期维护，建议直接换 @unhead/vue。