VitePress 搭建技术博客完全指南

作为一个独立开发者，拥有一个自己的技术博客几乎是标配——沉淀知识、建立个人品牌、偶尔还能接到合作。但市面上的博客系统要么太重（WordPress），要么主题生态眼花缭乱挑花眼（Hexo），要么要花钱托管。

直到我遇到 VitePress：Vue 团队出品，Markdown 写作，Vite 加持，免费部署。这篇就完整聊聊怎么用它搭一个技术博客。

为什么是 VitePress

简单说三个理由：

• 写作体验顺：以 Markdown 为核心，frontmatter 管理元数据，专注内容
• 性能极好：静态产物 + 按需加载，Lighthouse 基本满分
• 可玩性高：能在 Markdown 里直接嵌 Vue 组件，做交互式文档

Vue、Vite、Pinia 这些知名项目的官方文档都是 VitePress 建的，扛得住技术场景。

五分钟搭起来

1. 初始化项目

mkdir my-blog && cd my-blog
npm init -y
npm install -D vitepress vue

2. 建目录结构

my-blog/
├── docs/
│   ├── index.md          # 首页
│   ├── .vitepress/
│   │   ├── config.mts    # 主配置
│   │   └── theme/
│   │       ├── index.ts
│   │       └── custom.css
│   ├── posts/            # 博客文章
│   │   ├── index.md
│   │   └── hello.md
│   └── public/           # 静态资源
└── package.json

3. 写配置

docs/.vitepress/config.mts 是核心：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的博客',
  description: '记录技术与思考',
  lang: 'zh-CN',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '博客', link: '/posts/' },
      { text: '关于', link: '/about' }
    ],
    search: { provider: 'local' },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/yourname' }
    ]
  }
})

4. 写首页

docs/index.md 用 VitePress 的 Hero 布局：

---
layout: home
hero:
  name: 我的博客
  text: 记录技术与思考
  actions:
    - theme: brand
      text: 开始阅读
      link: /posts/
---

5. 启动

npx vitepress dev docs

打开 http://localhost:5173，你的博客就跑起来了。

文章怎么写

每篇文章就是一个 .md 文件，开头加 frontmatter：

---
title: 文章标题
date: 2026-08-11
tags: [前端, VitePress]
excerpt: 一句话摘要
---

# 正文开始

正常写 Markdown 就行。

代码高亮、表格、列表这些 Markdown 标准语法全部支持，还能指定代码块语言做语法高亮。

部署到哪里

构建出来的是纯静态文件，免费托管平台一大把：

平台	特点	适合
Cloudflare Pages	全球 CDN，国内访问还行	推荐，免费额度充足
Vercel	体验最好，自动部署	GitHub 仓库
GitHub Pages	完全免费，配 GitHub Actions	开源项目

构建命令：

npx vitepress build docs

产物在 docs/.vitepress/dist，往上面任一平台一丢就行。

几个实用小技巧

自定义域名：大多数平台都支持绑定自己的域名，配个 CNAME 就行。

全文搜索：VitePress 自带本地搜索，一行配置开启，不用接第三方。

深色模式：默认主题自带深浅色切换，不用自己写。

RSS 订阅：需要装个插件 vitepress-plugin-rss，配置稍繁琐但能用。

它的局限

说句实在话，VitePress 默认是文档站基因，做纯博客有几个地方要自己补：

• 没有现成的「文章列表自动生成」，得手动维护或写脚本
• 评论系统要接第三方（推荐 Giscus，基于 GitHub Discussions）
• 访问统计要接 Umami / Google Analytics

但这些都不是大问题，一次性配好就一劳永逸。

小结

如果你想要一个写作顺手、性能拉满、不用花钱、维护省心的技术博客，VitePress 是目前性价比很高的选择。一个人也能拥有专业级的博客站点。

这篇博客本身，就是用 VitePress 搭的。所见即所得。