GABA BLOG

Appearance

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

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

VitePress

基于 GABA Blog 实际项目，详细解析 VitePress 技术博客的基础架构设计、技术栈选型、项目组织和开发环境配置

标签：
Vue 3 TypeScript
发布于 2025年12月19日

项目概述 ​

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

核心特性 ​

  • 现代化技术栈：VitePress 2.0 + Vue 3 + TypeScript
  • 优雅的样式系统：Tailwind CSS + DaisyUI 双主题
  • 组件化开发：自动组件注册 + 模块化架构
  • 性能优化：Vite 构建优化 + Vercel 部署
  • 开发者体验：完整的 TypeScript 支持 + 路径别名系统

技术栈选型分析 ​

package.json 配置解析 ​

json
{
  "name": "gaba-blog",
  "version": "1.0.0",
  "description": "Personal technical blog built with VitePress - sharing daily development notes and travel records",
  "author": "GABA <calmly_li@outlook.com>",
  "license": "MIT",
  "keywords": [
    "blog",
    "vitepress",
    "vue",
    "typescript",
    "technical-blog",
    "personal-website"
  ],
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview",
    "update": "pnpm update && pnpm build"
  },
  "packageManager": "pnpm@10.25.0+sha512.5e82639027af37cf832061bcc6d639c219634488e0f2baebe785028a793de7b525ffcd3f7ff574f5e9860654e098fe852ba8ac5dd5cefe1767d23a020a92f501",
  "devDependencies": {
    "@iconify/vue": "^5.0.0",
    "@tailwindcss/typography": "^0.5.19",
    "autoprefixer": "^10.4.22",
    "daisyui": "4.12.24",
    "postcss": "^8.5.6",
    "tailwindcss": "^3.4.18",
    "typescript": "^5.9.3",
    "vitepress": "2.0.0-alpha.15"
  },
  "dependencies": {
    "motion-v": "^1.7.4",
    "vue": "^3.5.25"
  }
}

技术栈选择理由 ​

  1. VitePress 2.0.0-alpha.15

    • 基于 Vite 4，构建速度极快
    • Vue 3 组合式 API 支持
    • 现代化的开发体验

  2. TypeScript 5.9.3

    • 类型安全，减少运行时错误
    • 更好的 IDE 支持
    • 提高代码可维护性

  3. Tailwind CSS 3.4.18 + DaisyUI 4.12.24

    • 原子化 CSS，样式复用性高
    • DaisyUI 提供丰富的组件库
    • 支持明暗双主题切换

  4. PNPM 包管理器

    • 磁盘空间利用率高
    • 安装速度快
    • 严格的依赖管理

项目目录结构设计 ​

核心目录结构 ​

gaba-blog/
├── .vitepress/                    # VitePress 配置目录
│   ├── config.mts                # 主配置文件
│   ├── theme/                    # 主题目录
│   │   ├── components/          # 组件目录
│   │   ├── hooks/              # 组合式函数
│   │   ├── utils/              # 工具函数
│   │   ├── config/             # 主题配置
│   │   ├── styles/             # 样式文件
│   │   └── types/              # TypeScript 类型定义
│   └── content-loader.data.ts   # 内容加载器
├── src/                         # 源码目录
│   ├── articles/               # 文章目录
│   ├── assets/                 # 静态资源
│   └── *.md                    # 页面文件
├── package.json                # 项目配置
├── tsconfig.json               # TypeScript 配置
├── tailwind.config.js          # Tailwind 配置
├── postcss.config.js           # PostCSS 配置
└── vercel.json                 # Vercel 部署配置

设计理念 ​

  1. 关注点分离

    • 配置与代码分离
    • 主题与内容分离
    • 组件与逻辑分离

  2. 模块化设计

    • 每个目录有明确的职责
    • 组件按功能分类
    • 工具函数按用途分组

  3. 可扩展性

    • 易于添加新功能
    • 便于维护和升级
    • 支持团队协作

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/*"],
      "@theme/*": ["./.vitepress/theme/*"],
      "@components/*": ["./.vitepress/theme/components/*"]
    },
    
    "noEmit": true,
    "isolatedModules": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    
    "jsx": "preserve"
  },
  
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    ".vitepress/**/*.ts",
    ".vitepress/**/*.tsx",
    ".vitepress/**/*.vue",
    ".vitepress/**/*.mts"
  ],
  
  "exclude": [
    "node_modules",
    "dist",
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

关键配置说明 ​

  1. 目标版本：ES2020，充分利用现代 JavaScript 特性
  2. 严格模式：启用所有严格类型检查选项
  3. 路径别名：简化导入路径，提高代码可读性
  4. 模块解析：使用 bundler 模式，兼容 Vite 构建
  5. 包含范围：明确指定需要编译的文件类型

开发环境配置 ​

VSCode 开发环境 ​

推荐的扩展 ​

  • Volar：Vue 3 语言支持
  • Tailwind CSS IntelliSense：Tailwind 自动补全
  • TypeScript Vue Plugin：Vue 文件中的 TypeScript 支持
  • Iconify IntelliSense：图标自动补全

工作区设置 ​

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

开发脚本使用 ​

bash
# 开发模式
pnpm dev

# 构建生产版本
pnpm build

# 预览构建结果
pnpm preview

# 更新依赖并构建
pnpm update

路径别名系统 ​

别名配置（.vitepress/config.mts） ​

typescript
resolve: {
  alias: {
    // 根目录
    "@vitepress": resolve(__dirname, "./"),
    // 主题根目录
    "@theme": resolve(__dirname, "./theme"),

    // 主要功能目录
    "@components": resolve(__dirname, "./theme/components"),
    "@composables": resolve(__dirname, "./theme/composables"),
    "@config": resolve(__dirname, "./theme/config"),
    "@hooks": resolve(__dirname, "./theme/hooks"),
    "@styles": resolve(__dirname, "./theme/styles"),
    "@types": resolve(__dirname, "./theme/types"),
    "@utils": resolve(__dirname, "./theme/utils"),
  },
},

别名使用示例 ​

typescript
// 使用路径别名导入
import ArticleCard from '@components/small/ArticleCard.vue';
import { getDailyQuote } from '@utils/dailyQuote.mjs';
import type { Post } from '@types/content-loader.data';

总结 ​

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

  1. 技术选型合理：选择了成熟且活跃的技术栈
  2. 项目结构清晰：目录结构明确，易于维护
  3. 开发体验优秀：完整的 TypeScript 支持和路径别名
  4. 可扩展性强：模块化设计便于功能扩展
  5. 性能优化考虑：从架构层面考虑性能问题

通过这样的架构设计，项目不仅具有良好的开发体验，也为后续的功能扩展和性能优化打下了坚实的基础。在后续的文章中，我们将深入探讨主题定制、组件开发和部署优化等高级主题。

Last updated: