Skip to content

Meta 与 SEO 配置 ​

VitePress 提供了完善的 Meta 标签和 SEO 配置选项,帮助你优化搜索引擎排名和社交媒体分享效果。

基本配置 ​

全局 Meta 配置 ​

在配置文件中设置全局 Meta 信息:

ts
// docs/.vitepress/config.mts
export default defineConfig({
  // 站点标题
  title: 'VitePress 学习指南',
  
  // 站点描述(用于 SEO)
  description: '从入门到精通的 VitePress 完整教程',
  
  // 站点关键词
  head: [
    ['meta', { name: 'keywords', content: 'VitePress, Vue, 静态站点, 文档生成, SSG' }],
    ['meta', { name: 'author', content: 'VitePress 学习指南' }]
  ]
})

页面级 Meta 配置 ​

在 Markdown 文件的 frontmatter 中设置:

markdown
---
title: 路由配置指南
description: 详细介绍 VitePress 路由系统的工作原理和配置方法
keywords:
  - VitePress
  - 路由
  - 配置
author: VitePress 团队
---

Head 配置 ​

添加 Meta 标签 ​

ts
// docs/.vitepress/config.mts
export default defineConfig({
  head: [
    // 基础 Meta
    ['meta', { charset: 'utf-8' }],
    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    
    // SEO 相关
    ['meta', { name: 'robots', content: 'index, follow' }],
    ['meta', { name: 'googlebot', content: 'index, follow' }],
    
    // 语言
    ['meta', { 'http-equiv': 'content-language', content: 'zh-CN' }]
  ]
})

Canonical URL ​

设置规范链接,避免重复内容问题:

ts
export default defineConfig({
  head: [
    ['link', { rel: 'canonical', href: 'https://your-domain.com/' }]
  ]
})

页面级设置:

markdown
---
canonicalUrl: https://your-domain.com/guide/routing
---

Open Graph 配置 ​

Open Graph 协议用于控制社交媒体分享时的展示效果。

全局 OG 配置 ​

ts
// docs/.vitepress/config.mts
export default defineConfig({
  head: [
    // Open Graph
    ['meta', { property: 'og:type', content: 'website' }],
    ['meta', { property: 'og:site_name', content: 'VitePress 学习指南' }],
    ['meta', { property: 'og:title', content: 'VitePress 学习指南' }],
    ['meta', { property: 'og:description', content: '从入门到精通的 VitePress 完整教程' }],
    ['meta', { property: 'og:image', content: 'https://your-domain.com/og-image.png' }],
    ['meta', { property: 'og:url', content: 'https://your-domain.com/' }],
    ['meta', { property: 'og:locale', content: 'zh_CN' }]
  ]
})

页面级 OG 配置 ​

markdown
---
title: 主题定制指南
description: 学习如何自定义 VitePress 主题样式
head:
  - - meta
    - property: og:title
      content: 主题定制指南 - VitePress
  - - meta
    - property: og:description
      content: 学习如何自定义 VitePress 主题样式
  - - meta
    - property: og:image
      content: https://your-domain.com/images/theme-guide.png
---

OG 图片最佳实践 ​

规格推荐值
尺寸1200 x 630 像素
格式PNG 或 JPEG
文件大小< 1MB
文字安全区中心 1080 x 566 像素

生成 OG 图片的示例:

vue
<!-- docs/.vitepress/components/OgImage.vue -->
<template>
  <div class="og-image">
    <h1>{{ title }}</h1>
    <p>{{ description }}</p>
    <div class="brand">VitePress 学习指南</div>
  </div>
</template>

<style scoped>
.og-image {
  width: 1200px;
  height: 630px;
  padding: 80px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}
</style>

Twitter Card 配置 ​

Twitter 使用自己的卡片协议:

ts
export default defineConfig({
  head: [
    // Twitter Card
    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
    ['meta', { name: 'twitter:site', content: '@your_twitter_handle' }],
    ['meta', { name: 'twitter:title', content: 'VitePress 学习指南' }],
    ['meta', { name: 'twitter:description', content: '从入门到精通的 VitePress 完整教程' }],
    ['meta', { name: 'twitter:image', content: 'https://your-domain.com/twitter-card.png' }]
  ]
})

Twitter Card 类型 ​

类型说明
summary标题、描述、小图
summary_large_image标题、描述、大图
player视频/音频播放器
app应用下载卡片

结构化数据 ​

JSON-LD 配置 ​

添加结构化数据以增强搜索结果展示:

ts
// docs/.vitepress/config.mts
export default defineConfig({
  head: [
    ['script', { type: 'application/ld+json' }, JSON.stringify({
      "@context": "https://schema.org",
      "@type": "WebSite",
      "name": "VitePress 学习指南",
      "description": "从入门到精通的 VitePress 完整教程",
      "url": "https://your-domain.com",
      "potentialAction": {
        "@type": "SearchAction",
        "target": "https://your-domain.com/search?q={search_term_string}",
        "query-input": "required name=search_term_string"
      }
    })]
  ]
})

文章结构化数据 ​

markdown
---
title: VitePress 入门指南
date: 2026-04-01
author: 张三
head:
  - - script
    - type: application/ld+json
    - |
      {
        "@context": "https://schema.org",
        "@type": "Article",
        "headline": "VitePress 入门指南",
        "datePublished": "2026-04-01",
        "author": {
          "@type": "Person",
          "name": "张三"
        }
      }
---

SEO 最佳实践 ​

1. 标题优化 ​

markdown
---
# 好的标题:包含关键词,长度适中(50-60字符)
title: VitePress 路由配置完整指南 | 从入门到精通

# 不好的标题:过长或无关
title: 这里是一个非常长的标题,包含了太多不必要的信息
---

2. 描述优化 ​

markdown
---
# 好的描述:清晰、简洁、包含关键词(150-160字符)
description: 详细介绍 VitePress 路由系统的工作原理、配置方法和最佳实践,帮助你快速构建文档站点。

# 不好的描述:重复堆砌关键词
description: VitePress 路由 VitePress 配置 路由配置 文档站点
---

3. URL 结构 ​

ts
// 保持 URL 简洁、语义化
export default defineConfig({
  cleanUrls: true,  // 移除 .html 后缀
  
  // 使用重写规则优化 URL
  rewrites: {
    'guide/getting-started-with-vitepress.md': 'guide/getting-started.md'
  }
})

4. 语义化 HTML ​

使用正确的标题层级:

markdown
# 一级标题(每页仅一个)

## 二级标题

### 三级标题

5. 图片优化 ​

markdown
<!-- 添加 alt 属性 -->
![VitePress 架构图](./images/architecture.png "VitePress 架构图"){width="800" height="600"}

<!-- 使用图片标题 -->
![数据流程图](./images/flow.png){title="数据从输入到输出的完整流程"}

sitemap.xml ​

VitePress 自动生成 sitemap.xml:

ts
export default defineConfig({
  sitemap: {
    hostname: 'https://your-domain.com',
    
    // 排除特定页面
    exclude: ['/private/', '/draft/'],
    
    // 自定义 URL 选项
    transformItems: (items) => {
      return items.map(item => {
        // 设置优先级
        if (item.url.includes('/guide/')) {
          item.priority = 0.8
        }
        // 设置更新频率
        if (item.url === '/') {
          item.changefreq = 'daily'
        }
        return item
      })
    }
  }
})

robots.txt ​

创建 public/robots.txt:

txt
# 允许所有爬虫
User-agent: *
Allow: /

# 禁止特定目录
Disallow: /private/
Disallow: /draft/

# Sitemap 位置
Sitemap: https://your-domain.com/sitemap.xml

多语言 SEO ​

hreflang 标签 ​

VitePress 自动为多语言站点添加 hreflang 标签:

ts
export default defineConfig({
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN'
    },
    en: {
      label: 'English',
      lang: 'en-US'
    }
  }
})

生成的 HTML:

html
<link rel="alternate" hreflang="zh-CN" href="https://your-domain.com/">
<link rel="alternate" hreflang="en-US" href="https://your-domain.com/en/">
<link rel="alternate" hreflang="x-default" href="https://your-domain.com/">

性能与 SEO ​

核心网页指标 ​

优化 Core Web Vitals:

ts
export default defineConfig({
  head: [
    // 预连接
    ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
    ['link', { rel: 'dns-prefetch', href: 'https://analytics.google.com' }],
    
    // 预加载关键资源
    ['link', { rel: 'preload', href: '/fonts/main.woff2', as: 'font', type: 'font/woff2', crossorigin: '' }]
  ]
})

图片懒加载 ​

markdown
<!-- 默认启用懒加载 -->
![截图](./images/screenshot.png){loading="lazy"}

SEO 检查清单 ​

检查项状态
每页有唯一的 title☐
每页有唯一的 description☐
使用语义化 HTML 标签☐
图片有 alt 属性☐
URL 简洁、可读☐
配置了 sitemap.xml☐
配置了 robots.txt☐
OG 标签完整☐
Twitter Card 配置☐
结构化数据☐
多语言 hreflang☐

调试工具 ​

测试 OG 标签 ​

SEO 分析工具 ​

完整配置示例 ​

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'VitePress 学习指南',
  description: '从入门到精通的 VitePress 完整教程',
  lang: 'zh-CN',
  cleanUrls: true,
  
  head: [
    // 基础 Meta
    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    ['meta', { name: 'keywords', content: 'VitePress, Vue, SSG, 文档' }],
    ['meta', { name: 'author', content: 'VitePress 学习指南' }],
    ['meta', { name: 'robots', content: 'index, follow' }],
    
    // Canonical
    ['link', { rel: 'canonical', href: 'https://your-domain.com/' }],
    
    // Open Graph
    ['meta', { property: 'og:type', content: 'website' }],
    ['meta', { property: 'og:site_name', content: 'VitePress 学习指南' }],
    ['meta', { property: 'og:title', content: 'VitePress 学习指南' }],
    ['meta', { property: 'og:description', content: '从入门到精通的 VitePress 完整教程' }],
    ['meta', { property: 'og:image', content: 'https://your-domain.com/og.png' }],
    ['meta', { property: 'og:url', content: 'https://your-domain.com/' }],
    ['meta', { property: 'og:locale', content: 'zh_CN' }],
    
    // Twitter Card
    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
    ['meta', { name: 'twitter:site', content: '@vitepress' }],
    ['meta', { name: 'twitter:title', content: 'VitePress 学习指南' }],
    ['meta', { name: 'twitter:description', content: '从入门到精通的 VitePress 完整教程' }],
    ['meta', { name: 'twitter:image', content: 'https://your-domain.com/og.png' }],
    
    // 预连接
    ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }]
  ],
  
  sitemap: {
    hostname: 'https://your-domain.com'
  }
})

相关资源 ​

贡献者

加载中...

想要成为贡献者?

在 CNB 上参与贡献