我的文档

简体中文

English

简体中文

English

主题

VitePress 完整搭建指南 ​

本指南完全基于 VitePress 官方文档，用最简单的语言教你从零搭建文档网站。

📚 本页导航 ​

VitePress 是什么 ​

简单说：VitePress 是一个把 Markdown 文件变成漂亮网站的工具。

为什么要用它？ ​

  • 📝 超简单 - 只需要写 Markdown（像写 Word 文档一样）
  • ⚡ 超快 - 打开速度快，修改后立即看到效果
  • 🎨 很好看 - 默认主题就很专业
  • 🌙 深色模式 - 自动支持，用户可以切换
  • 🔍 有搜索 - 内置搜索功能

谁在用它？ ​

Vue.js、Vite、Vitest 等知名项目的官方文档都用 VitePress。

开始前的准备 ​

1. 需要安装的软件 ​

  • Node.js 20 或更高版本（必须）
    • 下载地址：https://nodejs.org/
    • 安装完后，打开命令行输入 node --version 检查是否安装成功

2. 准备一个代码编辑器 ​

3. 检查是否准备好 ​

打开命令行（Windows 是 CMD 或 PowerShell），输入：

bash
node --version
npm --version

如果都显示版本号，说明准备好了！

第一步：安装 VitePress ​

1. 创建项目文件夹 ​

bash
# 创建一个文件夹
mkdir my-docs
cd my-docs

解释

  • mkdir 是创建文件夹的命令
  • cd 是进入文件夹的命令
  • my-docs 是你的项目名，可以改成任何你喜欢的名字

2. 初始化项目 ​

bash
npm init -y

解释

这会创建一个 package.json 文件，用来管理项目。-y 表示使用默认设置。

3. 安装 VitePress ​

bash
npm add -D vitepress

解释

  • npm add 是安装软件包的命令
  • -D 表示这是开发工具（不是网站的一部分）
  • 安装需要一些时间，耐心等待

4. 运行安装向导（推荐） ​

bash
npx vitepress init

这个向导会问你几个问题：

┌ 欢迎使用 VitePress!
│
◇ VitePress 应该把配置文件放在哪里？
│ ./docs        <-- 直接回车使用默认值
│
◇ VitePress 应该在哪里查找你的 Markdown 文件？
│ ./docs        <-- 直接回车
│
◇ 网站标题：
│ 我的文档站点   <-- 输入你的网站名
│
◇ 网站描述：
│ 一个很棒的文档站点  <-- 输入网站描述
│
◇ 主题：
│ 默认主题      <-- 直接回车
│
◇ 使用 TypeScript？
│ 否           <-- 选择"否"（新手推荐）
│
◇ 添加 VitePress 脚本到 package.json？
│ 是           <-- 选择"是"
│
└ 完成！

注意

如果向导报错或不想用向导，可以手动创建配置文件和首页（见下一节"第二步"）。

第二步：启动网站 ​

启动开发服务器 ​

bash
npm run docs:dev

成功的标志：

vitepress v1.6.4
➜  Local:   http://localhost:5173/

打开浏览器，访问 http://localhost:5173/ 就能看到你的网站了！

小贴士

  • 修改 .md 文件后保存，网站会自动刷新
  • 按 Ctrl+C 可以停止服务器

第三步：配置网站 ​

现在让网站更完善！编辑 docs/.vitepress/config.js：

js
export default {
  // 网站基本信息
  title: '我的文档站点',
  description: '使用 VitePress 构建的文档网站',
  lang: 'zh-CN',  // 语言设置为中文
  
  // 主题配置
  themeConfig: {
    // 导航栏（网站顶部）
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide' },
      { text: '关于', link: '/about' }
    ],
    
    // 侧边栏（左侧菜单）
    sidebar: [
      {
        text: '开始',
        items: [
          { text: '介绍', link: '/guide' },
          { text: '安装', link: '/install' }
        ]
      }
    ],
    
    // 搜索功能
    search: {
      provider: 'local'  // 使用本地搜索
    },
    
    // 社交链接（右上角）
    socialLinks: [
      { icon: 'github', link: 'https://github.com/你的用户名/你的仓库' }
    ],
    
    // 页脚
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2024-present'
    }
  }
}

保存后，刷新浏览器就能看到变化！

下一步 ​

需要帮助？ ​

基于 MIT 许可发布 | 使用 VitePress 构建

Copyright © 2026-present