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 学习指南' }]
]
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
页面级 Meta 配置
在 Markdown 文件的 frontmatter 中设置：
markdown
---
title: 路由配置指南
description: 详细介绍 VitePress 路由系统的工作原理和配置方法
keywords:
- VitePress
- 路由
- 配置
author: VitePress 团队
---1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
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' }]
]
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Canonical URL
设置规范链接，避免重复内容问题：
ts
export default defineConfig({
head: [
['link', { rel: 'canonical', href: 'https://your-domain.com/' }]
]
})1
2
3
4
5
2
3
4
5
页面级设置：
markdown
---
canonicalUrl: https://your-domain.com/guide/routing
---1
2
3
2
3
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' }]
]
})1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
页面级 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
---1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
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>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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' }]
]
})1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
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"
}
})]
]
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
文章结构化数据
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": "张三"
}
}
---1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
SEO 最佳实践
1. 标题优化
markdown
---
# 好的标题：包含关键词，长度适中（50-60字符）
title: VitePress 路由配置完整指南 | 从入门到精通
# 不好的标题：过长或无关
title: 这里是一个非常长的标题，包含了太多不必要的信息
---1
2
3
4
5
6
7
2
3
4
5
6
7
2. 描述优化
markdown
---
# 好的描述：清晰、简洁、包含关键词（150-160字符）
description: 详细介绍 VitePress 路由系统的工作原理、配置方法和最佳实践，帮助你快速构建文档站点。
# 不好的描述：重复堆砌关键词
description: VitePress 路由 VitePress 配置 路由配置 文档站点
---1
2
3
4
5
6
7
2
3
4
5
6
7
3. URL 结构
ts
// 保持 URL 简洁、语义化
export default defineConfig({
cleanUrls: true, // 移除 .html 后缀
// 使用重写规则优化 URL
rewrites: {
'guide/getting-started-with-vitepress.md': 'guide/getting-started.md'
}
})1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
4. 语义化 HTML
使用正确的标题层级：
markdown
# 一级标题（每页仅一个）
## 二级标题
### 三级标题1
2
3
4
5
2
3
4
5
5. 图片优化
markdown
<!-- 添加 alt 属性 -->
{width="800" height="600"}
<!-- 使用图片标题 -->
{title="数据从输入到输出的完整流程"}1
2
3
4
5
2
3
4
5
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
})
}
}
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
robots.txt
创建 public/robots.txt：
txt
# 允许所有爬虫
User-agent: *
Allow: /
# 禁止特定目录
Disallow: /private/
Disallow: /draft/
# Sitemap 位置
Sitemap: https://your-domain.com/sitemap.xml1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
多语言 SEO
hreflang 标签
VitePress 自动为多语言站点添加 hreflang 标签：
ts
export default defineConfig({
locales: {
root: {
label: '简体中文',
lang: 'zh-CN'
},
en: {
label: 'English',
lang: 'en-US'
}
}
})1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
生成的 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/">1
2
3
2
3
性能与 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: '' }]
]
})1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
图片懒加载
markdown
<!-- 默认启用懒加载 -->
{loading="lazy"}1
2
2
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'
}
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43