Isaac Huo

中文

English

中文

English

Appearance

VitePress 博客搭建完全指南

• Isaac Huo

VitePress 博客搭建完全指南 ​

VitePress 是一个基于 Vite 和 Vue 3 的静态站点生成器，专为技术文档和博客而设计。本文将详细介绍如何使用 VitePress 搭建一个功能完整的博客网站。

为什么选择 VitePress？ ​

优势特点 ​

  1. 极快的开发体验：基于 Vite 的热重载，修改即时生效
  2. Vue 3 生态：完全支持 Vue 3 组件和 Composition API
  3. Markdown 增强：支持 Vue 组件、代码高亮、数学公式等
  4. SEO 友好：服务端渲染，搜索引擎优化
  5. 主题定制：灵活的主题系统，易于定制

与其他方案对比 ​

特性VitePressHexoHugoGatsby
构建速度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
学习成本⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
定制性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
生态系统⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐

快速开始 ​

环境准备 ​

bash
# 确保 Node.js 版本 >= 16
node --version

# 创建项目目录
mkdir my-blog
cd my-blog

# 初始化项目
npm init -y

安装 VitePress ​

bash
# 安装 VitePress
npm install -D vitepress

# 初始化 VitePress
npx vitepress init

项目结构 ​

my-blog/
├── .vitepress/
│   ├── config.ts          # 配置文件
│   └── theme/              # 自定义主题
├── blog/                   # 博客文章
├── public/                 # 静态资源
├── index.md               # 首页
package.json

配置详解 ​

基础配置 ​

typescript
// .vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的博客',
  description: '一个基于 VitePress 的个人博客',
  
  // 主题配置
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '博客', link: '/blog/' },
      { text: '关于', link: '/about' }
    ],
    
    sidebar: {
      '/blog/': [
        {
          text: '最新文章',
          items: [
            { text: 'VitePress 指南', link: '/blog/vitepress-guide' },
            { text: '第一篇博客', link: '/blog/first-post' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/username' }
    ]
  },
  
  // Markdown 配置
  markdown: {
    lineNumbers: true,
    theme: 'github-dark'
  }
})

多语言支持 ​

typescript
export default defineConfig({
  locales: {
    root: {
      label: '中文',
      lang: 'zh-CN'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Blog', link: '/en/blog/' }
        ]
      }
    }
  }
})

主题定制 ​

自定义样式 ​

css
/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #3498db;
  --vp-c-brand-light: #5dade2;
  --vp-c-brand-dark: #2980b9;
}

/* 自定义字体 */
.VPDoc {
  font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

/* 代码块样式 */
.vp-code-group .tabs {
  background: var(--vp-c-bg-mute);
}

自定义组件 ​

vue
<!-- .vitepress/theme/components/BlogList.vue -->
<template>
  <div class="blog-list">
    <article v-for="post in posts" :key="post.url" class="blog-item">
      <h3><a :href="post.url">{{ post.title }}</a></h3>
      <p class="meta">{{ formatDate(post.date) }}</p>
      <p>{{ post.description }}</p>
    </article>
  </div>
</template>

<script setup>
import { data as posts } from '../data/posts.data.js'

function formatDate(date) {
  return new Date(date).toLocaleDateString('zh-CN')
}
</script>

内容管理 ​

文章格式 ​

markdown
---
title: 文章标题
date: 2024-01-20
tags: [标签1, 标签2]
description: 文章描述
---

# 文章标题

文章内容...

## 代码示例

```javascript
const greeting = 'Hello VitePress!'
console.log(greeting)

数学公式 ​

$$E = mc^2$$

Vue 组件 ​


### 数据加载

```javascript
// .vitepress/theme/data/posts.data.js
import { createContentLoader } from 'vitepress'

export default createContentLoader('blog/*.md', {
  transform(rawData) {
    return rawData
      .map(({ url, frontmatter }) => ({
        url,
        title: frontmatter.title,
        date: frontmatter.date,
        description: frontmatter.description
      }))
      .sort((a, b) => new Date(b.date) - new Date(a.date))
  }
})

部署指南 ​

GitHub Pages ​

yaml
# .github/workflows/deploy.yml
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm
      
      - run: npm ci
      - run: npm run build
      
      - uses: actions/upload-pages-artifact@v2
        with:
          path: .vitepress/dist
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v2
        id: deployment

Vercel 部署 ​

json
{
  "buildCommand": "npm run build",
  "outputDirectory": ".vitepress/dist",
  "installCommand": "npm install"
}

性能优化 ​

图片优化 ​

markdown
<!-- 响应式图片 -->
<img src="/image.jpg" alt="描述" loading="lazy" />

<!-- WebP 格式 -->
<picture>
  <source srcset="/image.webp" type="image/webp">
  <img src="/image.jpg" alt="描述">
</picture>

代码分割 ​

typescript
// 动态导入组件
const HeavyComponent = defineAsyncComponent(() => 
  import('./components/HeavyComponent.vue')
)

最佳实践 ​

1. 内容组织 ​

  • 使用清晰的目录结构
  • 合理使用标签和分类
  • 保持文章命名一致性

2. SEO 优化 ​

  • 设置合适的 meta 信息
  • 使用语义化的 HTML 结构
  • 优化页面加载速度

3. 用户体验 ​

  • 响应式设计
  • 深色模式支持
  • 搜索功能
  • 评论系统

总结 ​

VitePress 是一个功能强大且易于使用的静态站点生成器，特别适合技术博客和文档网站。通过本文的介绍，你应该能够：

  1. 理解 VitePress 的核心概念和优势
  2. 搭建一个基础的博客网站
  3. 进行主题定制和功能扩展
  4. 部署到各种平台

希望这篇指南能帮助你快速上手 VitePress，打造属于自己的博客网站！

基于 MIT 许可证发布。

Copyright © 2024 Isaac Huo