如何使用VitePress搭建技术博客？-飞云脚本

VitePress 是 Vue 生态中由尤雨溪团队开发的静态站点生成器，核心优势是 开发服务器启动快、热更新迅速，并且默认支持 Markdown、Vue 组件嵌入以及现代化的主题样式，非常适合快速搭建技术博客或文档站点。以下是详细的搭建步骤和优化建议：

一、环境准备

首先确保你的开发环境安装了 Node.js（v18+ 推荐） 和 npm/yarn/pnpm（包管理器）。

检查 Node 版本：
```
node -v  # 需 ≥ 18.x
```

二、初始化 VitePress 项目

1. 创建项目目录并初始化

# 1. 创建博客目录（例如 my-tech-blog）
mkdir my-tech-blog && cd my-tech-blog

# 2. 初始化 npm 项目（一路回车即可）
npm init -y

# 3. 安装 VitePress 和 Vue（核心依赖）
npm install vitepress vue -D

2. 配置 package.json 脚本

打开 package.json，添加启动、构建和预览的脚本：

{
  "scripts": {
    "docs:dev": "vitepress dev docs",  // 开发模式（实时预览）
    "docs:build": "vitepress build docs",  // 构建静态文件
    "docs:preview": "vitepress preview docs"  // 预览构建结果
  }
}

三、创建目录结构和基础文件

VitePress 的默认源文件目录是 docs，推荐的目录结构如下：

my-tech-blog/
├─ docs/                # 博客源文件根目录
│  ├─ .vitepress/       # VitePress 配置目录
│  │  └─ config.ts      # 核心配置文件
│  ├─ posts/            # 博客文章目录（按日期或分类划分）
│  │  ├─ 2024-01-01-first-post.md
│  │  └─ 2024-01-10-vitepress-guide.md
│  ├─ public/           # 静态资源目录（图片、 favicon 等）
│  │  └─ avatar.png     # 示例图片
│  └─ index.md          # 博客首页
└─ package.json         # 项目配置

1. 编写首页（`docs/index.md`）

首页默认支持 Frontmatter（YAML 格式的元数据）和 Markdown 内容，可直接使用 VitePress 内置的首页布局：

---
# 首页元数据
title: 我的技术博客
description: 记录前端开发、技术踩坑和学习笔记
layout: home  # 指定使用首页布局
hero:
  name: 技术笔记
  text: 前端开发 & 学习记录
  tagline: 保持热爱，持续学习
  image:
    src: /avatar.png  # 静态资源需放在 public 目录
    alt: 博客头像
  actions:
    - theme: brand
      text: 查看文章
      link: /posts/  # 链接到文章列表页
    - theme: alt
      text: GitHub
      link: https://github.com/your-username  # 你的 GitHub 地址
features:
  - icon: ⚡️
    title: 技术分享
    details: 前端框架、工程化、性能优化等技术笔记
  - icon: 📝
    details: 记录踩坑经历和解决方案
  - icon: 🚀
    title: 学习成长
    details: 持续学习，分享成长心得
---

2. 编写第一篇博客文章（`docs/posts/2024-01-01-first-post.md`）

文章支持 Markdown 标准语法，以及 VitePress 扩展的 代码高亮、数学公式、Vue 组件嵌入 等功能：

---
title: 我的第一篇技术博客
date: 2024-01-01
categories: [前端, VitePress]
tags: [VitePress, 静态站点]
---

## 前言
今天开始用 VitePress 搭建我的技术博客啦！

## 什么是 VitePress？
VitePress 是基于 Vite 和 Vue 的静态站点生成器，特点是：
- 开发服务器启动快
- 热更新迅速
- 内置 Markdown 支持
- 支持 Vue 组件嵌入

## 代码示例
```javascript
// 示例：打印 Hello World
console.log('Hello, VitePress!');</code></pre>
<h2>嵌入 Vue 组件</h2>
<p>VitePress 支持直接在 Markdown 中嵌入 Vue 组件（需放在 `docs/.vitepress/components` 目录）：
<!-- <MyComponent /> --></p>
<pre><code>
### 四、配置 VitePress（<code>docs/.vitepress/config.ts</code>）
核心配置文件 <code>config.ts</code> 用于自定义博客的标题、导航栏、侧边栏、主题等。以下是常用配置示例：
```typescript
import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点基础配置
  base: '/my-tech-blog/',  // 若部署到 GitHub Pages，需填写仓库名称（默认 /）
  title: '我的技术博客',  // 站点标题
  description: '前端开发技术笔记',  // 站点描述（SEO 用）

  // 主题配置
  themeConfig: {
    // 导航栏配置
    nav: [
      { text: '首页', link: '/' },
      { text: '文章', link: '/posts/' },
      { text: '分类', link: '/categories/' },
      { text: '关于', link: '/about/' },
    ],

    // 侧边栏配置（可按目录自动生成）
    sidebar: [
      {
        text: '博客文章',
        items: [
          { text: '我的第一篇技术博客', link: '/posts/2024-01-01-first-post' },
          { text: 'VitePress 搭建指南', link: '/posts/2024-01-10-vitepress-guide' },
        ]
      }
    ],

    // 社交链接（右上角）
    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-username' },
      { icon: 'twitter', link: 'https://twitter.com/your-username' },
    ],

    // 页脚配置
    footer: {
      message: '© 2024 我的技术博客. All rights reserved.',
      copyright: 'Built with VitePress'
    }
  }
})

五、启动开发服务器

运行以下命令启动本地预览：

npm run docs:dev

启动后，访问 http://localhost:5173 即可看到博客首页，修改 Markdown 文件会实时热更新。

六、构建和部署

1. 构建静态文件

完成内容编写后，运行以下命令生成静态 HTML/CSS/JS 文件：

npm run docs:build

构建后的文件会输出到 docs/.vitepress/dist 目录。

2. 部署到 GitHub Pages（推荐）

确保你的项目已推送到 GitHub 仓库（仓库名建议为 your-username.github.io，这样可直接通过 https://your-username.github.io 访问）。
安装 gh-pages 工具（用于自动部署）：
```
npm install gh-pages -D
```

在 package.json 中添加部署脚本：

{
 "scripts": {
   // 其他脚本...
   "docs:deploy": "gh-pages -d docs/.vitepress/dist"
 }
}

运行部署命令：
```
npm run docs:deploy
```
部署成功后，访问 https://your-username.github.io 即可看到你的技术博客。

七、进阶优化

自定义主题：在 docs/.vitepress/theme 目录下创建 index.ts，可扩展或覆盖默认主题（需了解 Vue 3 和 VitePress 主题 API）。
添加评论系统：集成 Giscus（基于 GitHub Discussions）或 Valine 等评论工具（需在 config.ts 中配置）。
SEO 优化：在 config.ts 中配置 head 标签（添加关键词、 favicon 等）。
数学公式支持：安装 markdown-it-katex 插件，在 config.ts 中配置 Markdown 解析器。
图片优化：使用 VitePress 内置的 <img> 标签扩展（如 ![alt](path.jpg =300x200) 控制尺寸），或集成 vite-plugin-image-optimizer 插件。

总结

VitePress 凭借其 快速的开发体验、简洁的配置和强大的 Markdown/Vue 集成能力，是搭建技术博客的绝佳选择。按照以上步骤，你可以在半小时内快速搭建一个美观、高性能的技术博客，并部署到 GitHub Pages 供他人访问。