nuxt-seo

Nuxt SEO v5

状态：生产就绪 | 依赖项：Nuxt >=4.0.0

在构建 SEO 优化的 Nuxt 应用时使用此技能，可组合使用 8 个官方 Nuxt SEO 模块和独立模块。

---

快速入门（5 分钟）

1. 安装完整的 SEO 套件

# Recommended (v5)
npx nuxt module add @nuxtjs/seo

2. 配置站点设置

export default defineNuxtConfig({
  modules: ['@nuxtjs/seo'],

  site: {
    url: 'https://example.com',
    name: 'My Awesome Site',
    description: 'Building amazing web experiences',
    defaultLocale: 'en'
  }
})

重要（v5 破坏性变更）：

• site.name 不再根据 package.json 自动推断，必须显式设置
• 将 site.url 设置为生产环境 URL（站点地图和规范 URL 必需）
• 使用 i18n 时设置 defaultLocale

3. 重启并验证

访问以下 URL 进行验证：

• /robots.txt - Robots 文件
• /sitemap.xml - 站点地图
• /__robots__/debug-production.json - 调试（v5）
• /__sitemap__/debug-production.json - 调试（v5）

单独安装模块

npx nuxt module add @nuxtjs/robots
npx nuxt module add @nuxtjs/sitemap
npx nuxt module add nuxt-og-image

---

模块概览

模块	版本	用途
@nuxtjs/seo	v5.1.0	主要 SEO 模块（作为套件安装全部 8 个模块）
@nuxtjs/robots	v6.0.6	管理 robots.txt 和机器人检测
@nuxtjs/sitemap	v8.0.11	生成具有高级功能的 XML 站点地图
nuxt-og-image	v6.3.1	通过 Vue 模板创建 Open Graph 图像
nuxt-schema-org	v6.0.4	构建 Schema.org 结构化数据图
nuxt-link-checker	v5.0.6	通过 ESLint 集成查找并修复失效链接
nuxt-seo-utils	v8.1.4	SEO 工具、分享链接、网站图标、内联压缩
nuxt-site-config	v4.0.7	集中管理站点配置

独立模块（MIT）：nuxt-ai-ready（llms.txt）、nuxt-skew-protection（版本安全） Pro（付费）：Nuxt SEO Pro — Search Console、Core Web Vitals、MCP 服务

模块详细文档： 加载 references/module-details.md

---

关键规则

务必做到

• 在 nuxt.config.ts 中显式设置 site.url 和 site.name（v5：name 不再自动推断）
• 在多环境配置中使用环境变量
• 配置 robots.txt 以禁止抓取管理和私有页面
• 为所有重要页面添加 Schema.org 结构化数据
• 为社交分享生成 OG 图像
• 服务端使用 getSiteConfig(event)（v5：已移除 useSiteConfig(event)）
• 对 Content v3 使用 defineSitemapSchema()（v5：asSitemapCollection() 已弃用）

切勿这样做

• 忘记设置 site.url 和 site.name（会导致站点地图、规范 URL 和标题异常）
• 允许抓取暂存环境
• 在服务端使用 useSiteConfig(event)（v5：应使用 getSiteConfig(event)）
• 使用 asSitemapCollection()（v5：应使用 defineSitemapSchema()）
• 使用 getSiteIndexable()（v5：应使用 { indexable } = getSiteConfig(event)）

---

已知问题预防

问题 #1：未生成站点地图

错误：/sitemap.xml 返回 404 | 修复方法：在 nuxt.config.ts 中设置 site.url

问题 #2：缺少 robots.txt

错误：无法访问 /robots.txt | 修复方法：安装 @nuxtjs/robots 并设置 site.url

问题 #3：OG 图像无法渲染

错误：/__og-image__/og.png 返回错误 | 修复方法：使用兼容 Satori 的 CSS，或切换到 Chromium 渲染器

问题 #4：Schema 验证错误

错误：JSON-LD 无效 | 修复方法：遵循官方 Schema.org 类型，并使用 Google Rich Results Test 验证

问题 #5：内部链接失效

错误：内部链接返回 404 | 修复方法：在开发期间启用 nuxt-link-checker 和 ESLint 规则

问题 #6：重复的 Meta 标签

错误：存在多个属性相同的 Meta 标签 | 修复方法：让模块自动处理 Meta 标签

问题 #7：规范 URL 问题

错误：规范 URL 错误 | 修复方法：正确配置 site.url 和 trailingSlash

问题 #8：站点地图索引错误

错误：站点地图索引 XML 格式错误 | 修复方法：使用 chunkSize 选项拆分大型站点地图

问题 #9：暂存环境被抓取

错误：Google 将暂存环境编入索引 | 修复方法：disallow: process.env.NUXT_PUBLIC_ENV === 'staging' ? ['/'] : []

问题 #10：缺少社交分享图片

错误：社交媒体上没有预览 | 修复：在所有重要页面上使用 defineOgImage()

问题 #11：缺少站点名称（v5 重大变更）

错误：缺少站点标题/og:site_name | 修复：在 nuxt.config.ts 中设置 site.name，或设置 NUXT_SITE_NAME 环境变量 参考：https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5

问题 #12：服务端 useSiteConfig 错误（v5 重大变更）

错误：服务端出现 useSiteConfig is not a function | 修复：在服务端使用 getSiteConfig(event) 参考：https://github.com/harlan-zw/nuxt-site-config/releases

问题 #13：已弃用的内容组合式函数（v5 重大变更）

错误：asSitemapCollection is not defined | 修复：使用 defineSitemapSchema()、defineSchemaOrgSchema()、defineRobotsSchema() 参考：https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5

问题 #14：OG 图片安全错误（v5）

错误：OG 图片请求返回 403 或签名错误 | 修复：正确使用 defineOgImage()；不要手动构造 OG 图片 URL 参考：https://nuxtseo.com/docs/og-image/getting-started/introduction

---

配置示例

export default defineNuxtConfig({
  modules: ['@nuxtjs/seo'],

  site: {
    url: process.env.NUXT_PUBLIC_SITE_URL,
    name: 'My Site',
    defaultLocale: 'en'
  },

  robots: {
    disallow: process.env.NUXT_PUBLIC_ENV === 'staging' ? ['/'] : []
  },

  sitemap: {
    sitemaps: {
      blog: { sources: ['/api/__sitemap__/blog'] }
    }
  }
})

v5 新功能

• 社交分享链接：使用 useShareLinks({ title, twitter, utm }) 进行 UTM 跟踪
• 网站图标生成：npx nuxt-seo-utils icons --source logo.svg
• ESLint 链接检查：import linkChecker from 'nuxt-link-checker/eslint'
• definePageMeta 站点地图：definePageMeta({ sitemap: { changefreq: 'daily', priority: 0.8 } })
• 内联压缩：seo: { minify: true }

---

何时加载参考文件

根据用户的具体需求加载参考文件：

加载时机	参考文件
从 v4 升级到 v5、重大变更	references/v5-migration-guide.md
渲染模式、JSON-LD、规范 URL、IndexNow	references/seo-guides.md
AI 优化、llms.txt、MCP 工具	references/pro-modules.md
I18n SEO、路由规则、链接检查器规则	references/advanced-seo-guides.md
OG 图片模板、Satori/Chromium、字体	references/og-image-guide.md
Nuxt Content 集成、asSeoCollection	references/nuxt-content-integration.md
动态站点地图、多站点地图、分块	references/sitemap-advanced.md
服务端钩子、Nitro 插件	references/nitro-api-reference.md
llms.txt、AI 爬虫、内容信号	references/ai-seo-tools.md
模块功能概览	references/modules-overview.md
首次设置、包管理器相关细节	references/installation-guide.md
组合式函数 API 文档、参数列表	references/api-reference.md
博客、电商、多语言模式	references/common-patterns.md
特定模块配置	references/module-details.md
生产环境 SEO 指南	references/best-practices.md
错误解决、模块冲突	references/troubleshooting.md
多环境、高级功能	references/advanced-configuration.md

内置资源

Agent

Agent	用途
seo-auditor.md	全面 SEO 审核
schema-generator.md	生成 Schema.org 结构化数据
og-image-generator.md	创建自定义 OG 图片模板
link-checker.md	分析内部/外部链接
sitemap-builder.md	设计最佳站点地图策略

命令

命令	用途
/seo-audit	运行全面 SEO 审核
/seo-setup	快速设置 Nuxt SEO 项目
/og-preview	预览 OG 图片生成效果
/check-links	运行链接检查分析
/validate-sitemap	验证站点地图配置
/check-schema	验证 Schema.org 实现

资源文件

• assets/package-versions.json — 用于验证的当前模块版本

---

软件包版本（已于 2026-08-03 验证）

{
  "dependencies": {
    "@nuxtjs/seo": "^5.1.0",
    "@nuxtjs/robots": "^6.0.6",
    "@nuxtjs/sitemap": "^8.0.11",
    "nuxt-og-image": "^6.3.1",
    "nuxt-schema-org": "^6.0.4",
    "nuxt-link-checker": "^5.0.6",
    "nuxt-seo-utils": "^8.1.4",
    "nuxt-site-config": "^4.0.7"
  }
}

---

官方文档

• Nuxt SEO：https://nuxtseo.com
• v5 迁移：https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5
• @nuxtjs/robots：https://nuxtseo.com/docs/robots/getting-started/introduction
• @nuxtjs/sitemap：https://nuxtseo.com/docs/sitemap/getting-started/introduction
• nuxt-og-image：https://nuxtseo.com/docs/og-image/getting-started/introduction
• nuxt-schema-org：https://nuxtseo.com/docs/schema-org/getting-started/introduction
• nuxt-link-checker：https://nuxtseo.com/docs/link-checker/getting-started/introduction
• GitHub：https://github.com/harlan-zw

已可用于生产环境：所有模式均基于 https://nuxtseo.com/llms-full.txt 中的官方文档 | 上次验证：2026-08-03