VitePress 小白快速入门指南

写给零基础用户的知识库搭建全流程

📖 这份指南能帮你做什么？

用最短的时间，搭建一个像这样的个人知识库网站：

支持 Markdown 写作，所见即所得
自动生成侧边栏、导航栏、搜索
本地实时预览，改了马上看到效果
可发布到网络，供他人访问

🧰 第一步：确认你的环境

在开始之前，先检查 Node.js 是否已安装（你的电脑已经装好了 Node.js v20）。

打开 PowerShell，输入：

powershell

node -v
npm -v

看到类似 v20.x.x 和 10.x.x 就是正常的。

⚠️ 注意事项：Node.js 版本要求 18 及以上，你的 v20 完全满足。

🚀 第二步：初始化项目

2.1 创建项目文件夹（如果还没有）

powershell

# 创建目录（如果不存在）
mkdir "C:\Users\17377\WorkBuddy\Claw\my-knowledge-base"
cd "C:\Users\17377\WorkBuddy\Claw\my-knowledge-base"

2.2 初始化 npm 项目

powershell

npm init -y

这会在项目根目录生成一个 package.json 文件——相当于你项目的"身份证"。

2.3 安装 VitePress

powershell

npm add -D vitepress

⏳ 第一次安装会下载文件，耐心等待 1~3 分钟。
⚠️ 注意：-D 表示"开发依赖"，不要漏掉。

🏗️ 第三步：用向导快速生成初始结构

VitePress 提供了一个交互式向导，跟着提示走就行：

powershell

npx vitepress init

它会问你几个问题，推荐这样回答：

问题	推荐回答
Where should VitePress initialize the config?	`./docs`（直接回车）
Site title	你的知识库名称，例如 `我的知识库`
Site description	简单描述，例如 `个人学习笔记`
Theme	`Default Theme`（默认主题，直接回车）
Use TypeScript for config file?	`No`（初学者选 No）
Add VitePress npm scripts to package.json?	`Yes`（选是！）

✅ 完成后，会自动生成 docs/ 目录和相关配置文件。

📁 第四步：了解项目结构

生成后的目录结构大概是这样的：

my-knowledge-base/
├── docs/                    ← 所有内容都在这里
│   ├── .vitepress/
│   │   └── config.js        ← ⭐ 核心配置文件
│   ├── index.md             ← 首页
│   └── api-examples.md      ← 示例文章
├── package.json
└── node_modules/

最重要的两个东西：

docs/.vitepress/config.js — 配置导航、侧边栏、网站标题等
docs/ 目录下的 .md 文件 — 你的文章内容

✍️ 第五步：写你的第一篇文章

在 docs/ 目录下新建一个 .md 文件，例如 docs/my-first-note.md：

markdown

# 我的第一篇笔记

这是我的知识库第一篇文章！

## 学到了什么

- VitePress 很容易上手
- Markdown 语法很简洁

文章格式就是普通的 Markdown，和微信文章编辑器差不多。

⚙️ 第六步：配置导航和侧边栏

打开 docs/.vitepress/config.js，它大概长这样：

javascript

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: "我的知识库",
  description: "个人学习笔记",

  themeConfig: {
    // 顶部导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '笔记', link: '/my-first-note' }
    ],

    // 侧边栏
    sidebar: [
      {
        text: '学习笔记',
        items: [
          { text: '我的第一篇笔记', link: '/my-first-note' }
        ]
      }
    ],

    // 右上角社交链接（可选）
    socialLinks: []
  }
})

🔑 关键规则：link 里的路径不带 .md，只写文件名。例如文件是 docs/my-first-note.md，link 就写 /my-first-note。

🖥️ 第七步：本地预览

在项目根目录运行：

powershell

npm run docs:dev

成功后会看到：

  ➜  Local:   http://localhost:5173/

在浏览器打开 http://localhost:5173/，就能看到你的知识库了！

💡 修改 .md 文件或 config.js 后，浏览器会自动刷新，不用手动重启。

🔧 常用 Markdown 语法速查

VitePress 支持标准 Markdown，这里是最常用的：

markdown

# 一级标题
## 二级标题
### 三级标题

**粗体** 、 *斜体* 、 ~~删除线~~

- 无序列表项
- 另一项

1. 有序列表
2. 第二项

[链接文字](https://example.com)

![图片描述](./images/photo.png)

> 引用文字（像这样缩进）

`行内代码`

```python
# 代码块（支持语法高亮）
print("Hello VitePress!")
```

🌟 VitePress 特有的增强功能

除了普通 Markdown，VitePress 还支持这些实用功能：

提示框（Callout）

markdown

::: info 提示
这是一条信息。
:::

::: tip 小技巧
这是一个技巧。
:::

::: warning 注意
这是一个警告。
:::

::: danger 危险
这是危险操作提示。
:::

效果会显示为带颜色的提示框，非常醒目。

代码行高亮

markdown

```js{1,3}
const a = 1    // 第1行会高亮
const b = 2
const c = 3    // 第3行会高亮
```

📦 第八步：构建静态文件（准备发布）

本地写好之后，如果要发布到服务器，先构建：

powershell

npm run docs:build

构建完成后，会生成 docs/.vitepress/dist/ 目录，里面全是静态 HTML 文件。

把 dist/ 文件夹的内容上传到服务器（Nginx/Docker）就完成部署了。

🐳 第九步：部署方案概览

方案 A：Nginx 部署（推荐）

构建：npm run docs:build
将 docs/.vitepress/dist/ 内容复制到 Nginx 的 html 目录
Nginx 配置示例：

nginx

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # 解决刷新 404 的问题（重要！）
    location / {
        try_files $uri $uri/ /index.html;
    }
}

方案 B：Docker 部署

创建 Dockerfile（放在项目根目录）：

dockerfile

# 第一阶段：构建
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run docs:build

# 第二阶段：运行
FROM nginx:alpine
COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

然后运行：

powershell

docker build -t my-knowledge-base .
docker run -d -p 8080:80 my-knowledge-base

访问 http://localhost:8080 即可。

❗ 新手常见错误 & 解决方法

错误现象	原因	解决方法
`npm run docs:dev` 报错找不到命令	VitePress 未安装成功	重新运行 `npm add -D vitepress`
侧边栏/导航不显示新文章	`config.js` 没有添加对应 link	在 `sidebar` 和 `nav` 里添加新文章的路径
图片显示不出来	路径写错	图片放在 `docs/public/` 下，引用时写 `/图片名.png`
本地可以看，发布后刷新 404	Nginx 未配置 try_files	添加 `try_files $uri $uri/ /index.html;`
中文文件名链接乱码	文件名含中文	文件名改为英文，页面 title 可以是中文
修改 config.js 后没生效	配置文件语法错误	检查是否有多余的逗号、括号不匹配

📝 推荐的目录组织方式

随着文章越来越多，建议按分类建子文件夹：

docs/
├── .vitepress/
│   └── config.js
├── index.md              ← 首页
├── python/
│   ├── index.md          ← Python 分类首页
│   ├── basics.md
│   └── functions.md
├── tools/
│   ├── git.md
│   └── vscode.md
└── public/               ← 存放图片等静态资源
    └── logo.png

对应的 config.js 侧边栏配置：

javascript

sidebar: [
  {
    text: 'Python 学习',
    items: [
      { text: '入门基础', link: '/python/basics' },
      { text: '函数与模块', link: '/python/functions' }
    ]
  },
  {
    text: '工具使用',
    items: [
      { text: 'Git 基础', link: '/tools/git' },
      { text: 'VSCode 技巧', link: '/tools/vscode' }
    ]
  }
]

🎯 快速上手检查清单

[ ] Node.js v18+ 已安装（node -v 确认）
[ ] 项目目录已创建
[ ] npm init -y 已执行
[ ] npm add -D vitepress 已安装
[ ] npx vitepress init 已初始化
[ ] npm run docs:dev 能正常启动
[ ] 浏览器能访问 http://localhost:5173
[ ] 写了第一篇 .md 文章
[ ] 在 config.js 里配置了导航和侧边栏

完成以上全部，你就已经掌握 VitePress 的核心用法了！🎉

📚 进阶资源

官方文档：https://vitepress.dev/zh/
Markdown 语法参考：https://markdown.com.cn/
VitePress 主题配置：https://vitepress.dev/zh/reference/default-theme-config

本指南为 VitePress 1.x 版本，适用于 Node.js 18+

VitePress 小白快速入门指南 ​

写给零基础用户的知识库搭建全流程 ​

📖 这份指南能帮你做什么？ ​

🧰 第一步：确认你的环境 ​

🚀 第二步：初始化项目 ​

2.1 创建项目文件夹（如果还没有） ​

2.2 初始化 npm 项目 ​

2.3 安装 VitePress ​

🏗️ 第三步：用向导快速生成初始结构 ​

📁 第四步：了解项目结构 ​

✍️ 第五步：写你的第一篇文章 ​

⚙️ 第六步：配置导航和侧边栏 ​

🖥️ 第七步：本地预览 ​

🔧 常用 Markdown 语法速查 ​

🌟 VitePress 特有的增强功能 ​

提示框（Callout） ​

代码行高亮 ​

📦 第八步：构建静态文件（准备发布） ​

🐳 第九步：部署方案概览 ​

方案 A：Nginx 部署（推荐） ​

方案 B：Docker 部署 ​

❗ 新手常见错误 & 解决方法 ​

📝 推荐的目录组织方式 ​

🎯 快速上手检查清单 ​

📚 进阶资源 ​

VitePress 小白快速入门指南

写给零基础用户的知识库搭建全流程

📖 这份指南能帮你做什么？

🧰 第一步：确认你的环境

🚀 第二步：初始化项目

2.1 创建项目文件夹（如果还没有）

2.2 初始化 npm 项目

2.3 安装 VitePress

🏗️ 第三步：用向导快速生成初始结构

📁 第四步：了解项目结构

✍️ 第五步：写你的第一篇文章

⚙️ 第六步：配置导航和侧边栏

🖥️ 第七步：本地预览

🔧 常用 Markdown 语法速查

🌟 VitePress 特有的增强功能

提示框（Callout）

代码行高亮

📦 第八步：构建静态文件（准备发布）

🐳 第九步：部署方案概览

方案 A：Nginx 部署（推荐）

方案 B：Docker 部署

❗ 新手常见错误 & 解决方法

📝 推荐的目录组织方式

🎯 快速上手检查清单

📚 进阶资源