04 · VitePress 博客构建

把 markdown 笔记变成漂亮的可分享博客。

一、为什么是 VitePress

选项	优势	劣势
VitePress ✅	Vue 3 生态、默认主题清爽、本地搜索、热重载快	主题相对单一
Hexo	主题多、社区大	配置碎、构建慢
Hugo	极快	Go 语言、模板语法陡
Astro	现代、灵活	学习曲线
11ty	极简	默认丑
Next.js / Nuxt	全功能	杀鸡用牛刀

选 VitePress：为笔记型博客量身定做，5 分钟上手。

二、前置条件

安装 Node.js

bash

# macOS
brew install node

# 验证
node -v && npm -v

推荐 Node.js ≥ 20（VitePress 1.x 要求）。

三、初始化 VitePress

Step 1：创建 package.json

bash

cd ~/notes/我的主题

⚠️ 不要直接 npm init -y——npm 不接受中文目录名。手动创建：

json

{
  "name": "my-topic-blog",
  "version": "1.0.0",
  "description": "我的主题博客",
  "type": "module",
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview"
  },
  "private": true
}

Step 2：安装 VitePress

bash

npm install -D vitepress

Step 3：创建配置目录

bash

mkdir -p .vitepress

四、最小可用配置

`.vitepress/config.mts`

typescript

import { defineConfig } from 'vitepress'

export default defineConfig({
  lang: 'zh-CN',
  title: "我的主题博客",
  description: "学习与思考的归档地",

  // README.md 不进博客（仅作 Gitee/GitHub 仓库主页）
  srcExclude: ['README.md', 'node_modules/**'],

  // URL 重写：源文件中文名 → 博客英文 URL
  rewrites: {
    '01-快速入门.md': 'guide/quick-start.md',
    '02-完整规则.md': 'guide/rules.md',
    // ...
  },

  cleanUrls: true,
  lastUpdated: true,

  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '关于', link: '/about' },
    ],

    sidebar: {
      '/': [
        {
          text: '入门指南',
          items: [
            { text: '01 · 快速入门', link: '/guide/quick-start' },
            { text: '02 · 完整规则', link: '/guide/rules' },
          ],
        },
      ],
    },

    search: { provider: 'local' },

    outline: { level: [2, 3], label: '本页大纲' },
    docFooter: { prev: '上一篇', next: '下一篇' },
    lastUpdatedText: '最后更新',
  },
})

完整版本见 templates/vitepress-config.mts（GitHub 仓库）。

五、首页（hero 风格）

`index.md`

markdown

---
layout: home

hero:
  name: "我的主题博客"
  text: "副标题"
  tagline: 一句口号
  actions:
    - theme: brand
      text: 开始阅读
      link: /guide/quick-start
    - theme: alt
      text: 关于
      link: /about

features:
  - icon: 📚
    title: 入门指南
    details: 从零开始的系列文章
    link: /guide/quick-start
    linkText: 开始阅读

  - icon: 🕯️
    title: 实战记录
    details: 真实案例与思考
    link: /replays/001
    linkText: 第 1 篇
---

六、关键决策：URL 设计

问题：源文件中文名 vs 博客 URL 英文化

如果 01-快速入门.md 不映射，URL 就是 /01-快速入门，分享到微信会变成：

https://blog.vercel.app/%E5%BF%AB%E9%80%9F%E5%85%A5%E9%97%A8

长得很丑。

解决：rewrites + 英文 URL

typescript

rewrites: {
  '01-快速入门.md': 'guide/quick-start.md',
  '02-完整规则.md': 'guide/rules.md',
  '游戏复盘.md': 'replays/001.md',
}

效果：

✅ 源仓库还是 01-快速入门.md（中文圈友好）
✅ 博客 URL 是 /guide/quick-start（分享友好）

URL 命名建议

内容类型	URL 模式
教程系列	`/guide/<英文短词>`
复盘 / 日记	`/replays/<编号>` 或 `/journal/<日期>`
速查 / 工具	`/reference/<名称>`
关于页	`/about`

七、跨文件链接处理

⚠️ VitePress 不会自动跟随 rewrites 重写 markdown 内的相对链接。必须手动处理。

错误示范（会报死链）

markdown

继续读 [02-完整规则.md](./02-完整规则.md)

正确做法

博客内部跳转用绝对路径：

markdown

继续读 [完整规则](/guide/rules)

例外：README.md 里的链接保留中文

README.md 已经被 srcExclude 排除，它里面的中文 .md 链接给 Gitee/GitHub 仓库主页访客看的——保留中文路径。

八、本地预览

bash

npm run dev

访问 http://localhost:5173/。

热重载：改任何 .md 文件浏览器自动刷新。

九、生产构建

bash

npm run build

输出在 .vitepress/dist/。如果有死链会报错，按提示修复。

预览生产版本

bash

npm run preview

十、配置进阶

启用本地搜索

typescript

themeConfig: {
  search: {
    provider: 'local',
    options: {
      translations: {
        button: { buttonText: '搜索' },
        modal: {
          noResultsText: '没有找到相关结果',
          // ...
        },
      },
    },
  },
}

typescript

themeConfig: {
  footer: {
    message: '基于 VitePress 构建',
    copyright: '© 2026 你的名字',
  },
}

加 GitHub 链接

typescript

themeConfig: {
  socialLinks: [
    { icon: 'github', link: 'https://github.com/你的用户名/repo' },
  ],
}

暗色主题

VitePress 自动支持——右上角有切换按钮，跟随系统。

十一、常见坑

坑 1：npm init 报中文名错误

npm error Invalid name: "我的主题"

解决：手动写 package.json，name 字段用英文。

坑 2：跨文件链接死链

[vitepress] 9 dead link(s) found.
(!) Found dead link ./03-XXX in file 01-XXX.md

解决：把所有跨文件 markdown 链接改成绝对 URL（如 /guide/rules）。README.md 里的中文链接因为 srcExclude 不影响。

坑 3：rewrites 不生效

确保 rewrites 的 key 是带 .md 后缀的源文件名，value 也是带 .md 的：

typescript

rewrites: {
  '01-入门.md': 'guide/intro.md',   // ✅
  '01-入门': 'guide/intro',          // ❌ 没后缀
}

typescript

// ❌ 写源文件
{ text: '入门', link: '/01-入门' }

// ✅ 写 rewrite 后的 URL
{ text: '入门', link: '/guide/intro' }

下一步

本地能跑了 → 05-deploy.md 部署到 Vercel。

04 · VitePress 博客构建

一、为什么是 VitePress

二、前置条件

安装 Node.js

三、初始化 VitePress

Step 1：创建 package.json

Step 2：安装 VitePress

Step 3：创建配置目录

四、最小可用配置

`.vitepress/config.mts`

五、首页（hero 风格）

`index.md`

六、关键决策：URL 设计

问题：源文件中文名 vs 博客 URL 英文化

解决：rewrites + 英文 URL

URL 命名建议

七、跨文件链接处理

错误示范（会报死链）

正确做法

例外：README.md 里的链接保留中文

八、本地预览

九、生产构建

预览生产版本

十、配置进阶

启用本地搜索

自定义 footer

加 GitHub 链接

暗色主题

十一、常见坑

坑 1：npm init 报中文名错误

坑 2：跨文件链接死链

坑 3：rewrites 不生效

坑 4：sidebar 里的 link 写源文件名

下一步

💬 评论与建议

04 · VitePress 博客构建 ​

一、为什么是 VitePress ​

二、前置条件 ​

安装 Node.js ​

三、初始化 VitePress ​

Step 1：创建 package.json ​

Step 2：安装 VitePress ​

Step 3：创建配置目录 ​

四、最小可用配置 ​

.vitepress/config.mts ​

五、首页（hero 风格） ​

index.md ​

六、关键决策：URL 设计 ​

问题：源文件中文名 vs 博客 URL 英文化 ​

解决：rewrites + 英文 URL ​

URL 命名建议 ​

七、跨文件链接处理 ​

错误示范（会报死链） ​

正确做法 ​

例外：README.md 里的链接保留中文 ​

八、本地预览 ​

九、生产构建 ​

预览生产版本 ​

十、配置进阶 ​

启用本地搜索 ​

自定义 footer ​

加 GitHub 链接 ​

暗色主题 ​

十一、常见坑 ​

坑 1：npm init 报中文名错误 ​

坑 2：跨文件链接死链 ​

坑 3：rewrites 不生效 ​

坑 4：sidebar 里的 link 写源文件名 ​

下一步 ​

💬 评论与建议

04 · VitePress 博客构建

一、为什么是 VitePress

二、前置条件

安装 Node.js

三、初始化 VitePress

Step 1：创建 package.json

Step 2：安装 VitePress

Step 3：创建配置目录

四、最小可用配置

`.vitepress/config.mts`

五、首页（hero 风格）

`index.md`

六、关键决策：URL 设计

问题：源文件中文名 vs 博客 URL 英文化

解决：rewrites + 英文 URL

URL 命名建议

七、跨文件链接处理

错误示范（会报死链）

正确做法

例外：README.md 里的链接保留中文

八、本地预览

九、生产构建

预览生产版本

十、配置进阶

启用本地搜索

自定义 footer

加 GitHub 链接

暗色主题

十一、常见坑

坑 1：npm init 报中文名错误

坑 2：跨文件链接死链

坑 3：rewrites 不生效

坑 4：sidebar 里的 link 写源文件名

下一步