【Vue】VitePress 快速上手教程：从入门到放弃再到精通

🚀 VitePress 快速上手教程：从入门到放弃再到精通

📖 引言

🙂 老曹我今天要跟大家聊聊一个让前端开发者又爱又恨的东西——VitePress！这个由 Vite 和 Vue 驱动的静态站点生成器，简直就是前端圈的新宠儿。别问我为啥知道，问就是被它折磨过无数次！但话说回来，一旦你掌握了它，你会发现写文档就像呼吸一样自然（当然，前提是别被它气到窒息）。
原文链接：【Vue】VitePress 快速上手教程：从入门到放弃再到精通-CSDN博客

为啥要学 VitePress？因为它快！快到让你怀疑人生，快到让你觉得 Webpack 是上个世纪的产物。而且，它还支持 Vue 语法，这意味着你可以直接在 Markdown 里写 Vue 组件，是不是很骚？骚就对了，这正是现代前端的魅力所在！

🎯 学习目标

🎯 掌握 VitePress 的基本安装和配置
🎯 熟悉 VitePress 的目录结构和核心概念
🎯 学会自定义主题和页面布局
🎯 掌握导航栏、侧边栏配置技巧
🎯 了解如何部署 VitePress 站点
🎯 避免常见的 10 大坑（这个最重要！）

🛠️ 1. 环境准备与安装

😂 首先，老曹要提醒你，别一上来就 npm install，先检查下你的 Node.js 版本。VitePress 要求 Node.js版本 >= 18，低于这个版本？那就等着被各种奇怪的错误折磨吧！

bash

# 检查 Node.js 版本
node -v

# 如果版本过低，建议升级到最新 LTS 版本
# 推荐使用 nvm 管理 Node.js 版本

安装 VitePress 有两种方式，老曹推荐第二种，因为第一种会让你体验到什么叫"一步一个坑"：

✅方式一：手动创建（不推荐）

bash

# 创建项目目录
mkdir my-vitepress-site
cd my-vitepress-site

# 初始化 package.json
npm init -y

# 安装 VitePress
npm install -D vitepress

✅方式二：使用官方脚手架（强烈推荐）

bash

# 使用 create-vitepress 命令（需要 Node.js 18+）
npm create vitepress@latest my-vitepress-site

# 或者使用 npx
npx create-vitepress@latest my-vitepress-site

运行这个命令后，你会看到一个交互式界面，就像这样：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Which theme do you want to use?
│  Default Theme (Out of the box, good-looking docs)
│
◇  Use TypeScript?
│  No
│
◇  Add Vue DevTools?
│  No
│
└  Done! Now run `npm install` and `npm run docs:dev` to start the dev server.

😂 老曹建议新手选择默认主题，别一上来就搞什么自定义主题，不然你会发现自己在配置上浪费的时间比写内容还多！

📁 2. 目录结构解析

❗ 安装完成后，让我们来看看 VitePress 的目录结构。别小看这个结构，搞不清楚的话，后面你会发现自己像个无头苍蝇一样到处乱撞。

my-vitepress-site/
├── docs/
│   ├── api-examples.md
│   ├── index.md
│   ├── markdown-examples.md
│   └── .vitepress/
│       ├── config.mjs
│       └── theme/
│           └── index.js
├── package.json
└── README.md

让我用表格给你详细解释一下每个文件的作用：

文件/目录

作用说明

重要程度

docs/

存放所有文档内容的根目录

⭐⭐⭐⭐⭐

docs/index.md

首页内容文件

⭐⭐⭐⭐⭐

docs/.vitepress/

VitePress 配置文件目录

⭐⭐⭐⭐⭐

docs/.vitepress/config.mjs

主配置文件

⭐⭐⭐⭐⭐

docs/.vitepress/theme/

自定义主题目录

⭐⭐⭐

package.json

项目依赖和脚本配置

⭐⭐⭐⭐⭐

⚙️ 3. 配置文件详解

config.mjs 是 VitePress 的心脏，搞懂它你就成功了一半。来看看默认的配置文件长啥样：

javascript

// .vitepress/config.mjs
export default {
  title: "My VitePress Site",
  description: "A VitePress site",
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/markdown-examples' }
    ],
    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ]
  }
}

让我用图示来解释一下这个配置的结构：

config.mjs 配置结构
├── 基础配置
│   ├── title (站点标题)
│   └── description (站点描述)
└── themeConfig (主题配置)
    ├── nav (导航栏)
    │   ├── text (显示文本)
    │   └── link (链接地址)
    └── sidebar (侧边栏)
        ├── text (分组标题)
        └── items (菜单项列表)
            ├── text (菜单项文本)
            └── link (菜单项链接)

🎨 4. 自定义首页

🚧 VitePress 的首页配置是个让人又爱又恨的功能。默认的首页很简洁，但如果你想让它看起来更专业，就需要自定义了。

首先，修改 docs/index.md 文件：

---
layout: home

title: My Awesome Project
titleTemplate: Vite & Vue Powered Static Site

hero:
  name: My Awesome Project
  text: A VitePress Site
  tagline: My great project tagline
  actions:
    - theme: brand
      text: Get Started
      link: /markdown-examples
    - theme: alt
      text: View on GitHub
      link: https://github.com

features:
  - title: Feature 1
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature 2
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
  - title: Feature 3
    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
---

这个配置会产生这样的效果：

配置项

说明

示例效果

layout: home

指定使用首页布局

启用特殊首页样式

hero

英雄区域配置

大标题和行动按钮

features

特性展示区域

三列特性介绍

📚 5. 导航栏与侧边栏配置

🐱 导航栏和侧边栏是文档站点的灵魂，配置不好用户就会迷路。老曹来教你如何配置出既美观又实用的导航结构。

✅5.1 导航栏配置

javascript

// .vitepress/config.mjs
export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      {
        text: 'Dropdown Menu',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          {
            text: 'Sub Menu',
            items: [
              { text: 'Sub Item A', link: '/sub-item-a' },
              { text: 'Sub Item B', link: '/sub-item-b' }
            ]
          }
        ]
      }
    ]
  }
}

✅5.2 侧边栏配置

侧边栏配置更加灵活，支持多种配置方式：

javascript

// 方式一：简单数组形式
sidebar: [
  {
    text: 'Guide',
    items: [
      { text: 'Introduction', link: '/guide/introduction' },
      { text: 'Getting Started', link: '/guide/getting-started' }
    ]
  }
]

// 方式二：对象形式（支持多路径）
sidebar: {
  '/guide/': [
    {
      text: 'Guide',
      items: [
        { text: 'Introduction', link: '/guide/introduction' },
        { text: 'Getting Started', link: '/guide/getting-started' }
      ]
    }
  ],
  '/api/': [
    {
      text: 'API',
      items: [
        { text: 'Config', link: '/api/config' },
        { text: 'CLI', link: '/api/cli' }
      ]
    }
  ]
}

🎯 6. Markdown 扩展功能

👏 VitePress 对 Markdown 进行了扩展，让你能写出更丰富的文档。这些功能简直是文档作者的福音！

✅ 6.1 自定义容器

markdown

::: tip
这是一个提示
:::

::: warning
这是一个警告
:::

::: danger
这是一个危险警告
:::

::: details
这是一个详情块，在 IE / Edge 中不生效
:::

✅ 6.2 代码块高亮

javascript

// 行高亮
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
// [3-5]

html

<!-- Vue 组件高亮 -->
<template>
  <div>{{ msg }}</div>
</template>
<script>
export default {
  data() {
    return {
      msg: 'Hello World'
    }
  }
}
</script>

✅ 6.3 表格增强

Tables

Are

Cool

col 3 is

right-aligned

$1600

col 2 is

centered

$12

zebra stripes

are neat

🎨 7. 自定义主题与组件

⛄ 想要让你的站点与众不同？那就需要自定义主题和组件。老曹来教你如何操作。

首先，在 .vitepress/theme/ 目录下创建自定义组件：

html

<!-- .vitepress/theme/MyComponent.vue -->
<template>
  <div class="my-component">
    <h2>{{ title }}</h2>
    <p>{{ content }}</p>
  </div>
</template>

<script setup>
defineProps({
  title: String,
  content: String
})
</script>

<style scoped>
.my-component {
  border: 1px solid #ddd;
  padding: 20px;
  border-radius: 8px;
  background-color: #f9f9f9;
}
</style>

然后在 .vitepress/theme/index.js 中注册组件：

javascript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

现在你就可以在 Markdown 中使用这个组件了：

html

<MyComponent title="自定义组件" content="这是我的第一个自定义组件" />

🚀 8. 部署上线

🌽 写好了站点，最后一步就是部署上线。VitePress 支持多种部署方式，老曹推荐几种最常用的。

✅ 8.1 部署到 GitHub Pages

首先在 package.json 中添加部署脚本：

json

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    "docs:deploy": "gh-pages -d docs/.vitepress/dist"
  }
}

安装部署依赖：

bash

npm install -D gh-pages

✅ 8.2 部署到 Netlify

Netlify 部署最为简单，只需要创建一个 netlify.toml 文件：

toml

[build]
publish = "docs/.vitepress/dist"
command = "npm run docs:build"

然后将代码推送到 GitHub，Netlify 会自动部署。

✅ 8.3 部署到 Vercel

Vercel 配置也很简单，创建 vercel.json：

json

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist",
  "devCommand": "npm run docs:dev",
  "installCommand": "npm install"
}

💣 9. 10大踩坑幽默吐槽与解决方案

老曹我被 VitePress 虐过无数次，总结出以下10大坑，帮你少走弯路：

🕳️ 坑1：Node.js版本不兼容

问题描述：安装时报各种奇怪的错误
老曹吐槽：Node.js版本就像女朋友的脾气，不匹配就各种作妖
解决方案：升级到 Node.js 18+，推荐使用 nvm 管理版本

bash

# 使用 nvm 安装和切换版本
nvm install 18
nvm use 18

🕳️ 坑2：路径配置混乱

问题描述：链接404，找不到页面
老曹吐槽：路径配置就像走迷宫，一不小心就出不来
解决方案：确保所有链接以 [/](file://e:\上海前端项目\HTML面试项目\BFC问题.html) 开头，检查文件路径是否正确

javascript

// 正确写法
{ text: 'Guide', link: '/guide/' }

// 错误写法
{ text: 'Guide', link: 'guide/' }

🕳️ 坑3：侧边栏不显示

问题描述：侧边栏空白或不显示
老曹吐槽：侧边栏就像隐形人，你想看它的时候它偏偏不出现
解决方案：检查 config.mjs 中的 sidebar 配置，确保路径匹配

javascript

// 确保路径匹配
sidebar: {
  '/guide/': [ /* 侧边栏内容 */ ]
}

🕳️ 坑4：自定义组件不生效

问题描述：自定义组件无法显示
老曹吐槽：组件注册就像发朋友圈，发了不代表别人能看到
解决方案：检查组件是否正确注册，确保文件路径无误

javascript

// 确保在 enhanceApp 中注册组件
export default {
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

🕳️ 坑5：CSS样式丢失

问题描述：自定义样式不生效
老曹吐槽：CSS就像渣男，你说东它偏要西
解决方案：使用 scoped 样式或提高CSS优先级

html

<style scoped>
.my-class {
  color: red !important; /* 使用 !important 提高优先级 */
}
</style>

🕳️ 坑6：图片路径问题

问题描述：图片无法显示
老曹吐槽：图片路径就像快递地址，写错了就收不到货
解决方案：将图片放在 public 目录下，使用绝对路径引用

project/
├── docs/
├── public/
│   └── images/
│       └── logo.png

![Logo](/images/logo.png)

🕳️ 坑7：搜索功能异常

问题描述：搜索功能无法使用
老曹吐槽：搜索功能就像导航APP，关键时刻掉链子
解决方案：检查是否正确配置了搜索插件

javascript

themeConfig: {
  search: {
    provider: 'local'
  }
}

🕳️ 坑8：部署后样式错乱

问题描述：本地正常，部署后样式错乱
老曹吐槽：部署就像照镜子，你以为很美，实际上…
解决方案：检查 base 配置，确保与部署路径匹配

javascript

// 如果部署在子路径下
base: '/my-project/'

🕳️ 坑9：Markdown语法不识别

问题描述：某些 Markdown 语法不生效
老曹吐槽：Markdown解析器就像挑食的孩子，不是什么都能吃
解决方案：检查语法是否符合 VitePress 规范，或配置 Markdown 插件

javascript

markdown: {
  theme: 'material-palenight',
  lineNumbers: true
}

🕳️ 坑10：热重载失效

问题描述：修改文件后页面不自动刷新
老曹吐槽：热重载就像WiFi，信号不好时比没网还让人抓狂
解决方案：重启开发服务器，检查文件监听权限

bash

# 重启开发服务器
npm run docs:dev

📊 10. 功能对比表格总结

为了让老铁们更清楚地了解 VitePress，老曹整理了以下对比表格：

✅10.1 VitePress 与其他静态站点生成器对比

特性

VitePress

VuePress

Docusaurus

GitBook

构建速度

⭐⭐⭐⭐⭐

⭐⭐⭐

⭐⭐⭐⭐

⭐⭐

学习成本

⭐⭐⭐

⭐⭐⭐⭐

⭐⭐⭐

自定义性

⭐⭐⭐⭐

⭐⭐⭐⭐⭐

⭐⭐⭐⭐

⭐⭐

社区支持

⭐⭐⭐⭐

⭐⭐⭐⭐⭐

⭐⭐⭐⭐

部署难度

⭐⭐

⭐⭐⭐

⭐⭐⭐⭐

✅10.2 VitePress 核心功能支持情况

功能

支持情况

配置难度

推荐指数

Markdown 扩展

✅ 完全支持

⭐⭐

⭐⭐⭐⭐⭐

代码高亮

✅ 支持

⭐

⭐⭐⭐⭐⭐

搜索功能

✅ 内置支持

⭐⭐

⭐⭐⭐⭐

多语言支持

✅ 支持

⭐⭐⭐⭐

⭐⭐⭐

SEO优化

✅ 支持

⭐⭐

⭐⭐⭐⭐

PWA支持

✅ 插件支持

⭐⭐⭐

自定义主题

✅ 完全支持

⭐⭐⭐⭐⭐

⭐⭐⭐⭐

响应式设计

✅ 内置

⭐

⭐⭐⭐⭐⭐

🎯 11. 最佳实践建议

经过无数次踩坑，老曹总结出以下最佳实践：

✅11.1 项目结构建议

my-project/
├── docs/
│   ├── .vitepress/
│   │   ├── config.mjs
│   │   ├── theme/
│   │   └── public/
│   ├── guide/
│   ├── api/
│   ├── examples/
│   └── index.md
├── package.json
└── README.md

✅11.2 配置文件组织

javascript

// config.mjs - 按功能模块组织
import { defineConfig } from 'vitepress'

export default defineConfig({
  // 基础配置
  title: 'My Project',
  description: 'A great project documentation',
  base: '/',
  
  // 主题配置
  themeConfig: {
    // 导航栏
    nav: [],
    // 侧边栏
    sidebar: {},
    // 社交链接
    socialLinks: []
  },
  
  // Markdown配置
  markdown: {
    theme: 'material-palenight',
    lineNumbers: true
  },
  
  // 构建配置
  build: {
    outDir: '../dist'
  }
})

✅11.3 开发流程建议

初始化项目：使用官方脚手架快速搭建
配置导航：先规划好整体结构
编写内容：从核心内容开始
自定义样式：根据需要调整外观
测试部署：本地测试无误后再部署

🎉 结语

老曹我今天跟大家分享了 VitePress 的完整入门教程，从安装配置到部署上线，从踩坑指南到最佳实践，可以说是非常详尽了。虽然过程中可能会遇到各种问题，但只要你按照教程一步步来，相信你一定能掌握这个强大的静态站点生成器。

记住，前端技术就像打怪升级，每个坑都是经验值。VitePress 虽然有时候会让人抓狂，但它带来的开发体验和性能提升是值得的。希望这篇教程能帮到你，让你在前端文档写作的道路上越走越顺！

最后，别忘了多实践，多踩坑，多总结。只有真正动手做了，才能把知识变成自己的技能。老曹我在前端这条路上走了不少年，深知实践出真知的道理。加油，前端人们！

老曹寄语：技术之路漫漫，唯有不断学习和实践才能不断进步。VitePress 只是工具，真正的价值在于你用它创造了什么。愿每个前端开发者都能找到属于自己的技术之路！

【Vue】VitePress 快速上手教程：从入门到放弃再到精通 ​

🚀 VitePress 快速上手教程：从入门到放弃再到精通 ​

📖 引言 ​

🎯 学习目标 ​

🛠️ 1. 环境准备与安装 ​

✅方式一：手动创建（不推荐） ​

✅方式二：使用官方脚手架（强烈推荐） ​

📁 2. 目录结构解析 ​

⚙️ 3. 配置文件详解 ​

🎨 4. 自定义首页 ​

📚 5. 导航栏与侧边栏配置 ​

✅5.1 导航栏配置 ​

✅5.2 侧边栏配置 ​

🎯 6. Markdown 扩展功能 ​

✅ 6.1 自定义容器 ​

✅ 6.2 代码块高亮 ​

✅ 6.3 表格增强 ​

🎨 7. 自定义主题与组件 ​

🚀 8. 部署上线 ​

✅ 8.1 部署到 GitHub Pages ​

✅ 8.2 部署到 Netlify ​

✅ 8.3 部署到 Vercel ​

💣 9. 10大踩坑幽默吐槽与解决方案 ​

🕳️ 坑1：Node.js版本不兼容 ​

🕳️ 坑2：路径配置混乱 ​

🕳️ 坑3：侧边栏不显示 ​

🕳️ 坑4：自定义组件不生效 ​

🕳️ 坑5：CSS样式丢失 ​

🕳️ 坑6：图片路径问题 ​

🕳️ 坑7：搜索功能异常 ​

🕳️ 坑8：部署后样式错乱 ​

🕳️ 坑9：Markdown语法不识别 ​

🕳️ 坑10：热重载失效 ​

📊 10. 功能对比表格总结 ​

✅10.1 VitePress 与其他静态站点生成器对比 ​

✅10.2 VitePress 核心功能支持情况 ​

🎯 11. 最佳实践建议 ​

✅11.1 项目结构建议 ​

✅11.2 配置文件组织 ​

✅11.3 开发流程建议 ​

🎉 结语 ​

【Vue】VitePress 快速上手教程：从入门到放弃再到精通

🚀 VitePress 快速上手教程：从入门到放弃再到精通

📖 引言

🎯 学习目标

🛠️ 1. 环境准备与安装

✅方式一：手动创建（不推荐）

✅方式二：使用官方脚手架（强烈推荐）

📁 2. 目录结构解析

⚙️ 3. 配置文件详解

🎨 4. 自定义首页

📚 5. 导航栏与侧边栏配置

✅5.1 导航栏配置

✅5.2 侧边栏配置

🎯 6. Markdown 扩展功能

✅ 6.1 自定义容器

✅ 6.2 代码块高亮

✅ 6.3 表格增强

🎨 7. 自定义主题与组件

🚀 8. 部署上线

✅ 8.1 部署到 GitHub Pages

✅ 8.2 部署到 Netlify

✅ 8.3 部署到 Vercel

💣 9. 10大踩坑幽默吐槽与解决方案

🕳️ 坑1：Node.js版本不兼容

🕳️ 坑2：路径配置混乱

🕳️ 坑3：侧边栏不显示

🕳️ 坑4：自定义组件不生效

🕳️ 坑5：CSS样式丢失

🕳️ 坑6：图片路径问题

🕳️ 坑7：搜索功能异常

🕳️ 坑8：部署后样式错乱

🕳️ 坑9：Markdown语法不识别

🕳️ 坑10：热重载失效

📊 10. 功能对比表格总结

✅10.1 VitePress 与其他静态站点生成器对比

✅10.2 VitePress 核心功能支持情况

🎯 11. 最佳实践建议

✅11.1 项目结构建议

✅11.2 配置文件组织

✅11.3 开发流程建议

🎉 结语