从零搭建 VitePress 技术博客：GABA Blog 基础架构解析 |

项目概述

GABA Blog 是一个基于 VitePress 2.0 构建的个人技术博客，专注于分享日常开发笔记和旅行记录。项目采用现代化的前端技术栈，具有良好的开发体验和性能表现。

核心特性

现代化技术栈：VitePress 2.0 + Vue 3.5 + TypeScript 5.9
优雅的样式系统：Tailwind CSS 3.4 + DaisyUI 4.12 双主题
组件化开发：自动组件注册 + 模块化架构
测试支持：Vitest 单元测试 + 完整类型检查
代码质量：ESLint + Prettier + TypeScript 严格模式
性能优化：Vite 构建优化 + 图片压缩优化

技术栈选型分析

package.json 配置解析

json

{
  "name": "gaba-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview",
    "update": "pnpm update && pnpm build",
    "lint": "eslint . --ext .vue,.ts,.mts --fix",
    "format": "prettier --write \"**/*.{vue,ts,js,mts,md,json}\"",
    "type-check": "npx tsc --noEmit",
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage"
  },
  "packageManager": "pnpm@10.25.0",
  "devDependencies": {
    "@iconify/vue": "^5.0.0",
    "@tailwindcss/typography": "^0.5.19",
    "daisyui": "4.12.24",
    "typescript": "^5.9.3",
    "vitepress": "2.0.0-alpha.16",
    "vite-plugin-imagemin": "^0.6.1",
    "vitest": "^4.0.18",
    "eslint": "^9.39.2",
    "prettier": "^3.8.1"
  },
  "dependencies": {
    "motion-v": "^1.7.4",
    "vue": "^3.5.27"
  }
}

技术栈选择理由

VitePress 2.0.0-alpha.16
- 基于 Vite 5，构建速度极快
- Vue 3 组合式 API 支持
- 现代化的开发体验
- 强大的 Markdown 扩展支持
TypeScript 5.9.3
- 类型安全，减少运行时错误
- 更好的 IDE 支持
- 提高代码可维护性
Tailwind CSS 3.4.18 + DaisyUI 4.12.24
- 原子化 CSS，样式复用性高
- DaisyUI 提供丰富的组件库
- 支持 29 个主题切换
Vitest 4.0.18
- Vite 原生测试框架
- 快速的热更新测试
- Jest 兼容的 API
ESLint + Prettier
- 代码质量检查
- 统一的代码风格
- 自动修复支持

项目目录结构设计

项目采用 VitePress 标准目录结构，源码放在 src 目录，配置和主题代码放在 .vitepress 目录。

gaba-blog/
├── .vitepress/              # VitePress 配置与主题
│   ├── config.mts           # 主配置
│   ├── content-loader.data.ts
│   └── theme/               # 主题目录
├── src/                     # 源码目录
│   ├── articles/            # 文章
│   └── assets/              # 静态资源
├── test/                    # 测试
└── 配置文件                 # tsconfig.json, tailwind.config.js 等

设计理念

关注点分离：配置与代码分离，主题与内容分离
模块化设计：组件、hooks、工具函数按目录分组
可扩展性：易于添加新功能和升级

TypeScript 配置优化

tsconfig.json 详细解析

json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@vitepress/*": ["./.vitepress/*"],
      "@theme/*": ["./.vitepress/theme/*"],
      "@components/*": ["./.vitepress/theme/components/*"],
      "@hooks/*": ["./.vitepress/theme/hooks/*"],
      "@utils/*": ["./.vitepress/theme/utils/*"]
    },
    "noEmit": true,
    "isolatedModules": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "jsx": "preserve"
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.vue",
    ".vitepress/**/*.ts",
    ".vitepress/**/*.vue",
    ".vitepress/**/*.mts"
  ],
  "exclude": ["node_modules", "dist", "test"]
}

VitePress 配置详解

config.mts 核心配置

typescript

import { resolve } from 'path'
import { defineConfig } from 'vitepress'
import viteImagemin from 'vite-plugin-imagemin'

export default defineConfig({
  lang: 'zh-CN',
  title: 'GABA BLOG',
  description: '分享日常随笔',
  srcDir: './src',
  base: '/',
  metaChunk: true,
  lastUpdated: true,
  vite: {
    plugins: [
      viteImagemin({
        gifsicle: { optimizationLevel: 7, interlaced: false },
        optipng: { optimizationLevel: 7 },
        mozjpeg: { quality: 80 },
        pngquant: { quality: [0.8, 0.9], speed: 4 },
        svgo: { plugins: [{ name: 'removeViewBox' }] },
      }),
    ],
    resolve: {
      alias: {
        '@vitepress': resolve(__dirname, './'),
        '@theme': resolve(__dirname, './theme'),
        '@components': resolve(__dirname, './theme/components'),
        '@config': resolve(__dirname, './theme/config'),
        '@hooks': resolve(__dirname, './theme/hooks'),
        '@utils': resolve(__dirname, './theme/utils'),
        '@types': resolve(__dirname, './theme/types'),
      },
    },
    build: {
      cssCodeSplit: true,
      sourcemap: false,
      minify: 'esbuild',
    },
  },
  sitemap: {
    hostname: 'https://blog.crudclass.com',
  },
})

路径别名系统

别名	指向路径
`@vitepress`	`.vitepress/`
`@theme`	`.vitepress/theme/`
`@components`	`.vitepress/theme/components/`
`@config`	`.vitepress/theme/config/`
`@hooks`	`.vitepress/theme/hooks/`
`@utils`	`.vitepress/theme/utils/`
`@types`	`.vitepress/theme/types/`

开发环境配置

开发脚本使用

bash

# 开发模式（热更新）
pnpm dev

# 构建生产版本
pnpm build

# 预览构建结果
pnpm preview

# 更新依赖并构建
pnpm update

# 代码质量检查
pnpm lint
pnpm format
pnpm type-check

# 测试
pnpm test
pnpm test:ui
pnpm test:coverage

VSCode 开发环境

工作区设置

json

{
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "typescript.suggest.paths": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

总结

GABA Blog 的基础架构设计体现了现代前端开发的最佳实践：

技术选型合理：选择了成熟且活跃的技术栈
项目结构清晰：目录结构明确，易于维护
开发体验优秀：完整的 TypeScript 支持和路径别名
代码质量保障：ESLint + Prettier + Vitest 完整工具链
可扩展性强：模块化设计便于功能扩展
性能优化考虑：从架构层面考虑性能问题

通过这样的架构设计，项目不仅具有良好的开发体验，也为后续的功能扩展和性能优化打下了坚实的基础。

从零搭建 VitePress 技术博客：GABA Blog 基础架构解析

项目概述 ​

核心特性 ​

技术栈选型分析 ​

package.json 配置解析 ​

技术栈选择理由 ​

项目目录结构设计 ​

设计理念 ​

TypeScript 配置优化 ​

tsconfig.json 详细解析 ​

VitePress 配置详解 ​

config.mts 核心配置 ​

路径别名系统 ​

开发环境配置 ​

开发脚本使用 ​

VSCode 开发环境 ​

推荐的扩展 ​

工作区设置 ​

总结 ​

项目概述

核心特性

技术栈选型分析

package.json 配置解析

技术栈选择理由

项目目录结构设计

设计理念

TypeScript 配置优化

tsconfig.json 详细解析

VitePress 配置详解

config.mts 核心配置

路径别名系统

开发环境配置

开发脚本使用

VSCode 开发环境

推荐的扩展

工作区设置

总结