Nuxt3中useServerSeoMeta无法在服务端设置头部标签问题

问题描述 #

• 使用Nuxt3的useServerSeoMeta或useSeoMeta时，客户端SEO标签显示正常，但服务端渲染的页面源码（Ctrl+U查看）中，meta标签未按预期覆盖：
  • 若nuxt.config.js中配置了app.head.meta.title，服务端始终显示该全局配置值；
  • 移除全局标题配置后，服务端会生成基于访问路径的默认标题，依然无法读取页面级useSeoMeta的自定义设置。

用户代码示例：

useServerSeoMeta({
  title: 'My Amazing Site',
  ogTitle: 'My Amazing Site',
  description: 'This is my amazing site, let me tell you all about it.',
  ogDescription: 'This is my amazing site, let me tell you all about it.',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})

排查与解决步骤 #

1. 升级Nuxt版本
   确保使用Nuxt3稳定版（v3.0+），早期版本存在SEO元数据服务端渲染的已知bug，升级到最新稳定版可解决大部分基础问题。

2. 修正全局配置
   不要在nuxt.config.js的app.head.meta中直接设置title字段，改为通过titleTemplate定义模板，或完全移除全局标题配置，让页面级的SEO设置接管：

// nuxt.config.js
export default defineNuxtConfig({
  app: {
    head: {
      // 移除直接的title配置项
      // title: '全局默认标题',
      // 可选：设置标题模板，页面自定义title会替换%s
      titleTemplate: '%s - 我的站点',
      meta: [
        { charset: 'utf-8' },
        { name: 'viewport', content: 'width=device-width, initial-scale=1' }
        // 不要添加title相关的meta配置
      ]
    }
  }
})

3. 确保代码执行时机

• useServerSeoMeta需放在页面组件（pages/目录）或布局组件的顶层作用域，不要嵌套在客户端专属生命周期（如onMounted）中；
• useSeoMeta同理，需保证服务端渲染阶段能执行到该代码。

4. 生产环境验证
   开发模式下可能存在缓存或热更新异常，建议通过npm run build && npm run preview构建生产包后验证服务端渲染结果。

5. 排查第三方插件冲突
   若项目使用了第三方SEO插件（如nuxt-seo-kit），可能会和原生API产生冲突，暂时禁用插件测试是否恢复正常。

内容的提问来源于stack exchange，提问作者Pochen