个人博客自建指南（4）：博客构建 —— VitePress 从零到本地预览

前言

前三篇我们把开发环境搭好了（fnm + VSCode + pnpm），用 Vite 脚手架拉起了项目骨架，并用 Git 把代码托管到了码云。但到现在为止，你看到的还是一个 Vue + Vite 的欢迎页——那不是你的博客，只是用 Vite 脚手架拉起了一个标准的现代前端工程。这确保了我们的开发环境是健全的，也为后续的部署打下了基础。到这里，我们已经掌握了常规前端项目立项的基本流程。

本专栏的核心目标是 快速搭建一个个人博客，而不是开发一个复杂的前后端应用。如果继续沿用之前的 Vue 组件开发模式，我们需要处理路由、状态管理、接口联调等大量基建工作，这会让我们偏离“搭建写作容器”这个核心目标。

这篇开始，我们正式搭建博客本体。选用 VitePress —— Vue 官方出品的静态站点生成器，专为技术文档和博客设计。它的输入是 Markdown 文件，输出是纯静态 HTML，可以直接扔到任何 Web 服务器下运行。

传统博客（如 WordPress）需要在服务器上跑一个“动态程序”，每次访问都要查数据库生成页面。VitePress 相反——它在本地就把所有文章“编译”成纯 HTML 文件，放到服务器上直接就能访问，不需要数据库，也不需要后端程序。

本篇目标：在本地把 VitePress 跑起来，浏览器能看到博客首页。

关于“历史遗迹”的处理

既然我们要转向纯粹的内容创作型博客，之前那个基于 Vue 的 jiejinx-blog 项目（包含 src/目录和 App.vue）就已经完成了它的历史使命。它现在相当于一个“练手的沙箱”。

为了保持当前专栏的专注度，我们不再保留它。如果你以后想自写前端小工具，完全不需要在这个项目里翻找代码，你有两种更好的选择：

参考复刻：直接回顾第 1-3 篇的步骤，几分钟就能起一个新项目。
版本回溯：如果你用的是 Git，可以直接从第三篇（纯环境准备完成）的那个 Commit 节点拉出一个新分支来玩。

本篇章开始属于是新起了个项目，只是我们通过“覆盖”的方式，在当前目录下完成了环境的置换。

一、在现有项目中引入 VitePress

我们继续使用之前的 jiejinx-blog 项目目录。 VitePress 官方提供了脚手架工具，可以直接在当前项目根目录下初始化，无需手动创建目录和文件。

1.1 运行脚手架

打开终端，进入项目所在上级目录：

powershell

cd F:\web

然后运行 VitePress 初始化命令：

powershell

pnpm create vitepress

终端会依次询问几个问题，按如下回答：

? Site title: jiejinx-blog
? Target directory "F:\web\jiejinx-blog" is not empty. Remove existing files and continue?: y
#（输入 y，确认清理旧文件）

1.2 初始化后的目录结构

脚手架执行完毕后，你的 jiejinx-blog目录会变得极其干净。之前的 src/、public/、vite.config.ts等所有 Vue 相关的文件都已经被自动清理。

此时，你的项目根目录下就只有这四五个文件/文件夹，这就是全部了：

jiejinx-blog/
├── docs/                      # ✅ 博客文章的唯一根目录
│   ├── .vitepress/            # ✅ VitePress 配置目录
│   │   └── config.ts          # ✅ 核心配置文件
│   ├── index.md               # ✅ 博客首页（Markdown格式）
├── package.json               # ✅ 已自动更新
└── ...                        # 📂 其他旧的 Vue 文件已全部消失

💡 为什么不新建项目？直接在原项目上覆盖初始化，可以保持项目路径不变、Git 历史连续、依赖统一管理。VitePress 的脚手架会清理原项目内容，保证博客项目的干净清爽

1.3 手动更新依赖

pnpm create vitepress 调用的脚手架是社区个人维护的旧包（create-vitepress@0.0.6，3 年未更新），它生成的 package.json里依赖版本非常老旧：

json

"devDependencies": {
  "vue": "3.2.44",
  "vitepress": "1.0.0-alpha.28"
}

这些版本无法直接使用，需要手动升级到当前最新稳定版。

第一步：升级依赖版本

使用 npm-check-updates（简称 ncu）一键更新 package.json中的版本号：

powershell

# 全局安装 ncu（仅需执行一次）
pnpm add -g npm-check-updates

#进入项目根目录
cd F:\web\jiejinx-blog

# 检查并更新 vitepress 和 vue 到最新版本
ncu -u vitepress vue

⚠️ 常见错误：如果执行 pnpm add -g 时出现 [ERROR] The configured global bin directory "..." is not in PATH，说明 pnpm 的全局 bin 目录尚未添加到系统环境变量。解决方法：在终端中执行 pnpm setup，然后关闭当前终端窗口并重新打开，再重新运行上述命令 ( vscode 内的终端需要重启vscode后生效 )。
如果你在第2篇已经执行过 pnpm setup 并重启了终端，则不会遇到此问题。

执行后，package.json 中的版本号会自动更新为当前最新稳定版（如 vitepress 升至 1.6.4，vue 升至 3.5.39）。

第二步：配置 pnpm 11 构建白名单

pnpm 11 不再读取 package.json 中的 pnpm 字段（该字段应当直接删除，否则构建项目时会产生相关警告），需要在项目根目录新建 pnpm-workspace.yaml文件，使用以下命令一次性创建并写入配置：

powershell

#进入项目根目录
cd F:\web\jiejinx-blog

# 创建 pnpm-workspace.yaml 并写入配置
@"
packages:
  - "."
allowBuilds:
  esbuild: true
  vue-demi: true
"@ | Out-File -FilePath pnpm-workspace.yaml -Encoding utf8

为什么需要这一步？ esbuild 和 vue-demi 在安装时需要执行 postinstall 脚本（下载二进制文件、初始化兼容层）。pnpm 11 默认禁止依赖包运行任何脚本，必须通过 pnpm-workspace.yaml 显式放行。

1.4 验证安装

打开终端，进入项目根目录，安装项目依赖：

powershell

cd F:\web\jiejinx-blog
pnpm install

安装完成后，运行以下命令启动开发服务器：

powershell

pnpm run dev

终端输出类似：

  vitepress v1.6.4

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

浏览器打开 http://localhost:5173/，如果看到 VitePress 的默认首页，说明安装成功。你的博客已经在本地跑起来了。

二、写首页 + 第一篇测试文章

VitePress 的内容就是 Markdown （详细介绍看本文第五节）,我们来写两篇简单的文章，看看效果。

2.1 首页：docs/index.md

VitePress 会自动识别 layout: home 并渲染成首页样式。

markdown

---
layout: home

hero:
  name: "阶进遐的技术随笔"
  text: "编程经验分享 · 树莓派自建服务器 · 私有云架构实践"
  tagline: 从零搭建，每一步决策都记录。
---

2.2 测试文章：docs/guide/hello.md

markdown

# Hello VitePress

这是我的第一篇博客文章。

- 支持 **Markdown** 语法
- 支持 Vue 组件（后续进阶会讲到）

让我们开始吧！

三、核心配置：docs/.vitepress/config.ts

config.ts 是 VitePress 站点的总配置文件， config.ts 管"站点怎么呈现"——站点标题、导航栏、侧边栏、页脚、搜索、主题这些都在这里配。

本文只覆盖博客用得到的基础配置项（标题、导航、侧边、footer），更多配置（多语言、国际化、自定义主题继承等）见官方文档：
👉 VitePress 配置参考：Site Config | VitePress
👉 VitePress 主题配置参考：Default Theme Config | VitePress
⚠️ base 这个配置项尤其重要：博客挂在根域名下时必须设 base: '/'，如果以后改挂子路径（如 /blog/）再改这里。设错的话 build 后 assets/ 路径全 404，这个坑官方文档提得轻，实际很常见。

typescript

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '阶进遐的技术随笔',
  description: '编程经验分享 · 树莓派自建服务器 · 私有云架构实践',
  lang: 'zh-CN',

  // ⚠️ 关键：根域名部署必须设为 '/'，子路径部署改为 '/子路径/'
  base: '/',

  // 博客主题配置
  themeConfig: {
    // 顶部导航配置
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/hello' }
    ],

    // 侧边栏导航配置
    sidebar: {
      '/guide/': [
        {
          text: '入门',
          items: [
            { text: 'Hello VitePress', link: '/guide/hello' }
            ,{ text: 'md demo', link: '/guide/md-demo' }
          ]
        }
      ]
    },

    // 页脚配置
    footer: {
      message: '新ICP备19xxxx号-1',
      copyright: '阶进遐 © 2026'
    }
  }
})

四、本地预览+构建（闭环）

4.1 预览博客

打开终端（vscode中可用 ctrl+` ），在终端中运行：

powershell

pnpm run dev

终端输出类似：

 vitepress v1.6.4

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

浏览器打开 http://localhost:5173/，看到 VitePress 首页，左侧有文章列表，中间是正文。

至此，你的博客已经在本地跑起来了。你可以随时在 docs/ 目录下新建 .md 文件，保存后浏览器会自动刷新——这就是你的写作工作流。

4.2 构建博客

打开终端（vscode中可用 ctrl+` ），在终端中运行：

powershell

pnpm run build

终端输出类似：

  vitepress v1.6.4

✓ building client + server bundles...
✓ rendering pages...

构建完成，打开 docs/.vitepress/dist/ 目录，可以看到生成一堆 HTML 文件 —— 这就是你的博客的“静态版本”，可以直接扔到任何 Web 服务器下运行。

4.3 配置忽略规则 (.gitignore)

构建完成后，你会发现 docs/.vitepress/ 目录下多了 cache 和 dist 两个文件夹。这两个目录是机器自动生成的临时文件和静态产物，绝对不能提交到 Git 仓库（否则会导致仓库极其臃肿且频繁冲突）。

请在项目根目录下的 .gitignore 文件中追加以下内容（如果没有该文件，请新建一个）：

# VitePress 生成的缓存和构建产物
docs/.vitepress/dist
docs/.vitepress/cache

4.4 提交代码

现在，你的 Git 面板里应该只保留了 docs/ 目录下的 Markdown 源文件和 package.json 等核心配置文件。使用git提交代码，将你的第一篇博客代码正式保存到本地仓库和线上仓库。

4.4.1 在终端中操作（powershell）：

powershell

# 添加所有改动到暂存区
git add .

# 提交到本地仓库
git commit -m "feat: 初始化 VitePress 博客结构与文章"

# 推送到远程仓库（码云）
git push

这样，你的博客代码就安全地保存在了云端，同时本地也有了完整的版本历史。后续每次写完新文章，都可以用同样的流程：git add . → git commit -m "描述" → git push。

💡 如果 git push提示没有关联远程仓库，说明你跳过了第3篇的步骤。请先执行：
git remote add origin https://gitee.com/你的用户名/jiejinx-blog.git
然后再执行 git push -u origin master（首次推送需加 -u 建立追踪关系）。

4.4.2 在 VSCode 中操作（图形界面）：

打开左侧“源代码管理”图标（或按 Ctrl + Shift + G）
在“更改”区域可以看到修改的文件列表
在输入框中填写提交信息（如 feat: 初始化 VitePress 博客结构与文章）
按 Ctrl+Enter 或点击“提交”按钮（✔️ 图标）完成本地提交
提交后，点击底部状态栏的“同步更改”按钮（或点击“...”菜单 → “推送”）将代码推送到码云

推送成功后，刷新码云仓库页面，就能看到 docs/目录下的所有文件了。

五、Markdown 写作入门

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年提出，目标是"让文档易读易写，同时能方便地转成 HTML"。

它的核心思想是：用纯文本符号表达格式 —— 用 # 表示标题、用 ** 表示加粗、用 | 拼成表格，不用鼠标点、不用 <tag> 套。写出来的 .md 文件本身就是人能直接读的，同时也能被工具（VitePress、GitHub、Typora 等）原样转成排版好的 HTML。

为什么博客选 Markdown：

纯文本：Git 友好，diff、merge、blame 都顺手（你第三篇已经把 Git 托管跑通了）
专注内容：不用被 Word 的样式面板分心，写就是了
VitePress 原生支持：.md 文件 = VitePress 的输入源，Markdown 即 CMS

文件后缀用 .md（偶尔见 .markdown），VitePress 认 .md。

VitePress 的内容就是 Markdown。如果你还不熟悉 Markdown，掌握下面这些就够了 —— 本专栏的所有文章都是用这些语法写的。

5.0 Markdown 预览：

vscode 中打开 .md 文件，快捷键： ctrl+k → v , 即可打开预览窗口，查看排版效果。

5.1 标题

markdown

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

一级标题通常用作文章标题，二级标题用作章节，三级以下用作小节。

5.2 文本样式

markdown

**加粗**
*斜体*
~~删除线~~
`行内代码`

5.3 列表

无序列表：

markdown

- 苹果
- 香蕉
- 橘子

有序列表：

markdown

1. 第一步
2. 第二步
3. 第三步

嵌套列表（缩进两个空格）：

markdown

- 水果
  - 苹果
  - 香蕉
- 蔬菜
  - 白菜
  - 萝卜

5.4 链接与图片

markdown

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

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

图片路径可以是相对路径（相对于 docs/ 目录），也可以是网络图片链接。

5.5 引用

markdown

> 这是一段引用
> 可以有多行

5.6 代码块

普通代码块：

markdown

```python
print("Hello World")
```

行内代码：

markdown

这是 `print()` 函数

5.7 表格

markdown

| 姓名 | 年龄 | 城市 |
|------|------|------|
| 张三 | 25   | 北京 |
| 李四 | 30   | 上海 |
| 王五 | 28   | 广州 |

5.8 分割线（三个短横线即可生成一条水平分割线。）

markdown

---

5.9 行尾双空格 = 强制换行

Markdown 中，直接换行并不会在渲染时产生新行，而是会被合并为同一段落。若需要在不产生新段落的前提下强制换行，可以在行尾添加两个空格再回车。

markdown

第一行··
第二行

渲染效果：

第一行
第二行

两个空格在行尾等价于 HTML 的 <br> 标签，间距小于段落间的空白。常用于地址、诗歌、多行备注等场景。

若需要更大的段落间距，则用空行分隔：

第一行

第二行

这会生成两个独立的段落。

注意：VitePress 遵循 GFM（GitHub Flavored Markdown）规范，行尾双空格换行是标准行为，在表格、列表等复杂结构中同样适用。

5.10 VitePress 特有语法

以上是标准 Markdown 语法，在任何 Markdown 编辑器里都能用。VitePress 在此基础上扩展了几个特有语法 —— Frontmatter（文章元信息）和提示容器 —— 这些只在 VitePress 中生效，但非常实用。

Frontmatter（文章元信息）：写在文件最上方，用 --- 包裹。

markdown

---
title: 文章标题
date: 2026-07-10
tags: [VitePress, Markdown]
---

提示容器：

markdown

::: tip 提示
这是一条提示信息
:::

::: warning 警告
这是一条警告信息
:::

::: danger 危险
这是一条危险信息
:::

::: details 点击展开详情
这里是折叠内容
:::

5.11 练习：写一篇真正的博客文章

现在，打开 docs/guide/hello.md，把里面的测试内容替换成一篇真正的文章。你可以写一段自我介绍，或者记录一下搭建博客过程中遇到的一个小问题。保存后浏览器自动刷新，你就能看到效果。

下面是一篇示例文章，覆盖了上面提到的所有常见标记，你可以直接复制过去作为参考。

示例文章：docs/guide/md-demo.md

markdown

---
title: 我的第一篇博客文章
date: 2026-07-10
tags: [Markdown, VitePress, 入门]
---

# 我的第一篇博客文章

这是我的第一篇博客文章，用来演示 Markdown 的各种常见语法。

## 文本样式

这是一段普通文本，其中包含 **加粗**、*斜体*、~~删除线~~ 和 `行内代码`。

## 列表

### 无序列表

- 苹果
- 香蕉
- 橘子

### 有序列表

1. 第一步：安装 Node.js
2. 第二步：配置 fnm
3. 第三步：搭建 VitePress

### 嵌套列表

- 水果
  - 苹果
  - 香蕉
- 蔬菜
  - 白菜
  - 萝卜

## 引用

> 纸上得来终觉浅，绝知此事要躬行。
>
> —— 陆游

## 代码块
```javascript
function greet(name) {
console.log(`Hello, ${name}!`)
}
greet('VitePress')
```

## 表格

| 语法 | 用途 | 难度 |
|------|------|------|
| 标题 | 文章结构 | ⭐ |
| 列表 | 条目展示 | ⭐ |
| 代码块 | 代码展示 | ⭐⭐ |
| 表格 | 数据对比 | ⭐⭐ |
| Frontmatter | 文章元信息 | ⭐⭐⭐ |

## 提示容器

::: tip 提示
Markdown 语法非常简单，半小时就能上手。
:::

::: warning 注意
Frontmatter 必须写在文件最顶部，否则不会生效。
:::

::: danger 小心
不要用 Tab 缩进列表，VitePress 可能解析异常，建议用两个空格。
:::

## 分割线

---

## 双空格换行

第一行  
第二行

## 小结

以上就是在 VitePress 中写文章常用的 Markdown 语法。
掌握了这些，你就可以开始写博客了。后续随着需求增加，再逐步学习更多高级语法。

你可以把这篇示例文章保存为 docs/guide/md-demo.md，添加侧边栏导航链接配置：

typescript

# 找到 docs/.vitepress/config.ts 中如下位置添加

    // 侧边栏导航配置
    sidebar: {
      '/guide/': [
        {
          text: '入门',
          items: [
            { text: 'Hello VitePress', link: '/guide/hello' }
            //  添加 docs/guide/md-demo.md 链接入口
            ,{ text: 'md demo', link: '/guide/md-demo' }
          ]
        }
      ]
    },

然后在浏览器中查看效果。

熟悉这些Markdown 语法后，写文章就不会有障碍了。

💡 想深究 Markdown 语法，推荐两个入口：
👉 GFM 规范：https://github.github.com/gfm
（国内若打不开，可看 CommonMark 主规范 https://spec.commonmark.org ）
👉 VitePress Markdown 扩展（Frontmatter / 提示容器 / 代码块高亮等）:
https://vitepress.dev/guide/markdown

总结

这篇我们完成了：

在现有项目中引入 VitePress
写了首页和第一篇测试文章
配置了 config.ts（导航栏、侧边栏、页脚）
本地预览成功，博客在本地跑起来了

接下来你可以继续写 Markdown 文章，用 pnpm run build 构建出 dist/ 目录。用于发布上线。

个人博客自建指南（4）：博客构建 —— VitePress 从零到本地预览 ​

前言 ​

关于“历史遗迹”的处理 ​

一、在现有项目中引入 VitePress ​

1.1 运行脚手架 ​

1.2 初始化后的目录结构 ​

1.3 手动更新依赖 ​

第一步：升级依赖版本 ​

第二步：配置 pnpm 11 构建白名单 ​

1.4 验证安装 ​

二、写首页 + 第一篇测试文章 ​

2.1 首页：docs/index.md ​

2.2 测试文章：docs/guide/hello.md ​

三、核心配置：docs/.vitepress/config.ts ​

四、本地预览+构建（闭环） ​

4.1 预览博客 ​

4.2 构建博客 ​

4.3 配置忽略规则 (.gitignore) ​

4.4 提交代码 ​

4.4.1 在 终端 中操作（powershell）： ​

4.4.2 在 VSCode 中操作（图形界面）： ​

五、Markdown 写作入门 ​

为什么博客选 Markdown： ​

5.0 Markdown 预览： ​

5.1 标题 ​

5.2 文本样式 ​

5.3 列表 ​

5.4 链接与图片 ​

5.5 引用 ​

5.6 代码块 ​

5.7 表格 ​

5.8 分割线 （三个短横线即可生成一条水平分割线。） ​

5.9 行尾双空格 = 强制换行 ​

5.10 VitePress 特有语法 ​

5.11 练习：写一篇真正的博客文章 ​

总结 ​

个人博客自建指南（4）：博客构建 —— VitePress 从零到本地预览

前言

关于“历史遗迹”的处理

一、在现有项目中引入 VitePress

1.1 运行脚手架

1.2 初始化后的目录结构

1.3 手动更新依赖

第一步：升级依赖版本

第二步：配置 pnpm 11 构建白名单

1.4 验证安装

二、写首页 + 第一篇测试文章

2.1 首页：docs/index.md

2.2 测试文章：docs/guide/hello.md

三、核心配置：docs/.vitepress/config.ts

四、本地预览+构建（闭环）

4.1 预览博客

4.2 构建博客

4.3 配置忽略规则 (.gitignore)

4.4 提交代码

4.4.1 在终端中操作（powershell）：

4.4.2 在 VSCode 中操作（图形界面）：

五、Markdown 写作入门

为什么博客选 Markdown：

5.0 Markdown 预览：

5.1 标题

5.2 文本样式

5.3 列表

5.4 链接与图片

5.5 引用

5.6 代码块

5.7 表格

5.8 分割线（三个短横线即可生成一条水平分割线。）

5.9 行尾双空格 = 强制换行

5.10 VitePress 特有语法

5.11 练习：写一篇真正的博客文章

总结