当前位置：首页 > news >正文

VitePress实战：从零到一，构建你的专属技术文档与博客站点

news 2026/5/11 20:48:49

1. 为什么选择VitePress？

最近两年我帮团队搭建过十几个文档站点，试过Hexo、Docusaurus、VuePress等工具，最后发现VitePress才是技术文档和博客的最优解。举个真实案例：上周我用VitePress给开源项目重写文档，从零开始到部署上线只用了3小时，而之前用其他工具平均要折腾一整天。

VitePress的核心优势在于它的"三重基因"：

Vite基因：秒级热更新，保存文件后浏览器几乎实时刷新
Vue基因：可以在Markdown里直接写Vue组件，比如嵌入可交互的代码演示
Markdown基因：支持GFM扩展语法，表格、任务列表、emoji都能直接使用

实测对比下来，VitePress的启动速度比VuePress快5倍以上。我电脑上npm run dev的平均耗时：

VuePress：4.2秒
VitePress：0.8秒

提示：如果你需要频繁更新技术文档，这个速度优势会非常明显。我写Vue组件库文档时，经常要边改代码边调整文档，VitePress的即时反馈让这个流程顺畅很多。

2. 环境准备与项目初始化

2.1 基础环境配置

先检查你的开发环境是否符合要求：

Node.js版本 ≥16（推荐18+）
pnpm ≥7（比npm/yarn更快更省空间）

# 快速检查环境 node -v pnpm -v

如果还没安装pnpm，可以用这个命令全局安装：

npm install -g pnpm

2.2 创建项目

新建项目目录并初始化：

mkdir my-vitepress && cd my-vitepress pnpm init

安装VitePress核心包：

pnpm add -D vitepress

注意：这里用-D参数（开发依赖）是因为VitePress只在构建阶段需要，不需要打包进最终产物。

3. 基础配置与首页定制

3.1 配置文件结构

创建基本目录结构：

my-vitepress ├── docs │ ├── .vitepress │ │ └── config.mts │ └── index.md └── package.json

在config.mts中添加最小配置：

export default { title: '我的技术博客', description: '记录前端开发心得', themeConfig: { nav: [ { text: '首页', link: '/' }, { text: '项目', link: '/projects/' } ] } }

3.2 定制首页内容

修改docs/index.md文件：

--- layout: home hero: name: 我的技术空间 text: 记录与分享开发经验 tagline: 每周更新前端工程化实践 actions: - theme: brand text: 开始阅读 link: /guide/getting-started - theme: alt text: GitHub link: https://github.com/yourname ---

4. 高级主题配置实战

4.1 自定义布局组件

在.vitepress/theme目录下创建自定义组件：

.vitepress └── theme ├── index.ts └── MyFooter.vue

index.ts内容示例：

import DefaultTheme from 'vitepress/theme' import MyFooter from './MyFooter.vue' export default { extends: DefaultTheme, enhanceApp({ app }) { app.component('MyFooter', MyFooter) } }

MyFooter.vue示例：

<template> <footer class="my-footer"> © 2023 我的博客 | 使用VitePress构建 </footer> </template> <style scoped> .my-footer { margin-top: 2rem; text-align: center; color: #666; } </style>

4.2 集成Vite插件

VitePress可以直接使用Vite生态插件。比如添加图片压缩插件：

pnpm add -D vite-plugin-imagemin

然后在config.mts中配置：

import { defineConfig } from 'vitepress' import vitePluginImagemin from 'vite-plugin-imagemin' export default defineConfig({ vite: { plugins: [ vitePluginImagemin({ gifsicle: { optimizationLevel: 3 } }) ] } })

5. Markdown写作增强技巧

5.1 代码块的高级用法

VitePress支持代码组的展示方式：

::: code-group ```js [JavaScript] console.log('Hello VitePress') ``` ```ts [TypeScript] console.log('Hello VitePress') ``` :::

效果是生成带标签页切换的代码块，这在展示不同语言实现时特别有用。

5.2 在Markdown中使用Vue组件

新建docs/components/Demo.vue：

<template> <div class="demo"> <button @click="count++">点击 {{ count }}</button> </div> </template> <script setup> import { ref } from 'vue' const count = ref(0) </script>

然后在Markdown中直接使用：

<Demo />

6. 部署上线全攻略

6.1 静态资源构建

执行构建命令：

pnpm run docs:build

生成的静态文件默认在.vitepress/dist目录。我习惯添加快捷命令到package.json：

{ "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" } }

6.2 自动部署到GitHub Pages

创建.github/workflows/deploy.yml：

name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: pnpm/action-setup@v2 - uses: actions/setup-node@v3 with: node-version: 18 - name: Install dependencies run: pnpm install - name: Build run: pnpm run docs:build - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/.vitepress/dist

这个配置会在每次push到main分支时自动构建并部署到GitHub Pages。第一次部署后需要在仓库Settings → Pages中开启GitHub Pages服务。

查看全文

http://www.jsqmd.com/news/509829/