新手引导

欢迎来到 VitePress 学习指南！本页面帮助你在 5 分钟内 快速了解 VitePress，判断它是否适合你，并顺利开始学习。

🎯 VitePress 是什么？

VitePress 是由 Vue 团队开发的静态网站生成器（SSG），专门用于构建高性能的文档站点。

核心特点

特性	说明
⚡ 极速构建	基于 Vite，开发服务器启动 < 100ms，构建速度极快
📝 Markdown 驱动	用 Markdown 写内容，VitePress 自动生成精美页面
🎨 Vue 支持	在 Markdown 中直接使用 Vue 组件，扩展能力无限
🔍 内置搜索	开箱即用的本地全文搜索，无需额外配置
📱 响应式	完美适配桌面、平板、手机等设备
🌐 SEO 友好	自动生成 sitemap、结构化数据、meta 标签
💰 免费开源	MIT 协议，完全免费使用

适用场景

适用

• ✅ 技术文档站（如 Vue.js 官方文档）
• ✅ API 文档、组件库文档
• ✅ 个人技术博客
• ✅ 知识库 / Wiki
• ✅ 项目 README 扩展
• ✅ 产品帮助中心

不太适用

• ❌ 复杂动态网站（需要后端交互）
• ❌ 大型电商平台
• ⚠️ 内容型 CMS（建议使用 Nuxt/Next.js）

---

🔄 与其他工具对比

SSG 工具横向对比

特性	VitePress	Docusaurus	Nuxt Content	Docsify	VuePress
框架	Vue 3	React	Vue 3	无	Vue 2/3
构建引擎	Vite	Webpack	Vite	无	Webpack
开发体验	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
构建速度	⚡ 最快	中等	快	无需构建	较慢
主题定制	灵活	灵活	灵活	有限	灵活
插件生态	增长中	丰富	丰富	基础	成熟
多语言	✅ i18n	✅ i18n	✅ i18n	❌	✅ i18n
学习曲线	低	中	中	低	高

如何选择？决策树

你需要什么类型的站点？
│
├─ 动态网站（登录、支付、API）
│   └→ 使用 Nuxt.js / Next.js
│
├─ 文档站点
│   │
│   ├─ React 技术栈团队？
│   │   └→ 使用 Docusaurus
│   │
│   ├─ 追求极速开发和极致性能？
│   │   └→ ✅ 使用 VitePress ← 推荐！
│   │
│   ├─ 需要 Vue 2 兼容或成熟插件生态？
│   │   └→ 使用 VuePress
│   │
│   └─ 只想快速展示现有 MD 文档？
│       └→ 使用 Docsify（零配置）
│
└─ 博客 / 内容型网站
    └→ 使用 Nuxt Content / Hexo / Hugo

---

✅ 开始前的准备

环境要求检查清单

请确保你的开发环境满足以下要求：

环境要求

必要条件

要求	版本	检查命令
Node.js	>= 18.19	node --version
npm	>= 8.0	npm --version 或使用 pnpm/yarn
Git	任意版本	git --version
代码编辑器	推荐 VS Code	-

推荐安装

工具	说明	安装方式
pnpm	更快的包管理器	npm i -g pnpm
Vue DevTools	浏览器调试插件	Chrome 扩展商店

自检清单

在继续之前，请确认以下事项：

• [ ] 我已安装 Node.js 18.19+（运行 node --version 确认）
• [ ] 我有基本的 HTML/CSS 基础知识
• [ ] 我了解什么是 Markdown
• [ ] 我的电脑可以访问网络（用于安装依赖）

不了解 Markdown？ 不用担心！我们会在基础教程部分详细讲解。你也可以先看 Markdown 语法速查。

---

🚀 三步快速上手

第一步：创建项目

# 使用 npm
npm create vitepress@latest my-docs

# 或使用 pnpm（推荐）
pnpm create vitepress@latest my-docs

# 或使用 yarn
yarn create vitepress@latest my-docs

创建过程中会有以下选项：

? 选择项目类型：
  ○ 新建一个全新的项目（推荐新手）
  ● 把 VitePress 加入到已有项目中

第二步：启动开发服务器

cd my-docs
npm run docs:dev
# 或
pnpm docs:dev

启动后打开浏览器访问显示的地址（通常是 http://localhost:5173）。

第三步：编写内容

在 docs/index.md 中编辑内容：

---
layout: home
hero:
  name: "我的文档站"
  text: "欢迎使用 VitePress"
---

# Hello VitePress!

这是我的第一个文档站点。

保存文件后，页面会自动刷新！🎉

---

🗺️ 推荐学习路径

根据你的背景和目标，选择合适的学习路径：

路径一：零基础入门（推荐）

适合完全没有接触过 VitePress 的初学者。

graph LR
    A[📘 新手引导] --> B[📖 什么是 VitePress]
    B --> C[🔧 安装与环境配置]
    C --> D[📝 创建第一个页面]
    D --> E[🎨 了解基础功能]
    E --> F[💡 选择实战案例]

预计时间：2-3 小时
学习目标：能够独立搭建并部署一个基础的文档站点

路径二：从 VuePress 迁移

如果你已经熟悉 VuePress，想要迁移到 VitePress：

graph LR
    A[📦 迁移指南] --> B[🔄 配置差异对比]
    B --> C[⚙️ 插件兼容处理]
    C --> D[✅ 部署验证]

预计时间：30-60 分钟
学习目标：成功将 VuePress 项目迁移至 VitePress

路径三：进阶学习

适合已经完成基础学习的开发者：

graph LR
    A[🎨 主题定制] --> B[🧩 组件开发]
    B --> C[🔌 插件开发]
    C --> D[🌍 多语言支持]
    D --> E[📈 性能优化]

预计时间：5-10 小时
学习目标：掌握 VitePress 的高级特性和最佳实践

---

📚 下一步

准备好开始了吗？根据你的情况选择下一步：

你的情况	推荐操作
完全新手，想系统学习	👉 查看完整学习路径
想先了解 VitePress 是什么	👉 什么是 VitePress
准备好动手了	👉 安装与环境配置
有具体问题	👉 常见问题 FAQ
想看实际案例	👉 实战案例列表

---

💡 学习小贴士

高效学习建议

1. 边学边做：每学完一个章节就动手实践，不要只看不练
2. 善用搜索：遇到问题先用本站的搜索功能查找相关教程
3. 参考官方：VitePress 官方文档 是最权威的参考
4. 加入社区：有问题可以在 GitHub Discussions 提问
5. 记录笔记：用自己的话整理知识点，加深理解

常见误区

• ❌ 不要跳过基础直接学高级功能
• ❌ 不要死记硬背配置项，理解原理更重要
• ❌ 不要忽略错误信息，它们通常包含解决线索
• ❌ 不要害怕查阅源码，VitePress 的代码很易读

祝你学习愉快！如果在学习过程中遇到任何问题，欢迎通过以下方式获取帮助：

• 📖 查看 常见问题
• 🔍 使用站内搜索功能
• 💬 在 GitHub Issues 提问