📝 My Blog — React + TypeScript 博客系统

一个基于 React 18 + TypeScript + Vite 的博客系统前端，用于学习和巩固 React 工程化开发经验。本项目不接入真实后端，所有数据通过本地 Mock 和 localStorage 模拟。

技术栈

技术	用途
React 18+	UI 框架
TypeScript	类型系统
Vite	构建工具
React Router	路由管理
Tailwind CSS	样式方案
Zustand	状态管理
react-markdown	Markdown 渲染
lucide-react	图标库
clsx	className 合并

功能列表

• ✅ 博客文章列表（按时间倒序）
• ✅ 分页展示（每页 6 篇）
• ✅ 分类筛选（全部 / 按分类）
• ✅ 关键词搜索（搜索标题和摘要）
• ✅ 分类列表页（含文章数量）
• ✅ 分类文章列表（支持分页）
• ✅ 博客详情页（Markdown 渲染）
• ✅ Markdown 文件上传（.md / .markdown）
• ✅ 文件格式校验（类型、大小、非空）
• ✅ Frontmatter 自动解析（标题、分类、标签、摘要）
• ✅ 上传后自动创建文章并跳转详情
• ✅ localStorage 持久化（刷新后数据保留）
• ✅ 404 页面
• ✅ 空状态、加载状态、错误状态处理
• ✅ 分页越界自动修正

目录结构

src/
├── assets/                     # 静态资源
├── components/
│   ├── Common/                 # 通用组件
│   │   ├── EmptyState.tsx      # 空状态
│   │   ├── ErrorMessage.tsx    # 错误消息
│   │   └── Loading.tsx         # 加载状态
│   ├── Category/               # 分类组件
│   │   ├── CategoryCard.tsx    # 分类卡片
│   │   └── CategoryList.tsx    # 分类列表
│   ├── Layout/                 # 布局组件
│   │   ├── AppLayout.tsx       # 应用布局
│   │   ├── Header.tsx          # 顶部导航
│   │   └── Footer.tsx          # 页脚
│   ├── Pagination/             # 分页组件
│   │   └── Pagination.tsx      # 分页器
│   ├── Post/                   # 文章组件
│   │   ├── MarkdownRenderer.tsx# Markdown 渲染
│   │   ├── PostCard.tsx        # 文章卡片
│   │   ├── PostList.tsx        # 文章列表
│   │   └── PostMeta.tsx        # 文章元信息
│   └── Upload/                 # 上传组件
│       ├── MarkdownUploader.tsx# 文件上传器
│       └── PostUploadForm.tsx  # 上传表单
├── data/
│   ├── mockCategories.ts       # 分类 Mock 数据
│   └── mockPosts.ts            # 文章 Mock 数据
├── pages/
│   ├── CategoriesPage.tsx      # 分类列表页
│   ├── CategoryPostsPage.tsx   # 分类文章页
│   ├── HomePage.tsx            # 首页（博客列表）
│   ├── NotFoundPage.tsx        # 404 页面
│   ├── PostDetailPage.tsx      # 文章详情页
│   └── UploadPostPage.tsx      # 上传页面
├── router/
│   └── index.tsx               # 路由配置
├── services/
│   ├── categoryService.ts      # 分类 API 服务
│   └── postService.ts          # 文章 API 服务
├── store/
│   └── postStore.ts            # Zustand 状态管理
├── types/
│   └── blog.ts                 # 核心类型定义
├── utils/
│   ├── date.ts                 # 日期格式化
│   ├── markdown.ts             # Markdown 解析
│   ├── readingTime.ts          # 阅读时间计算
│   └── storage.ts              # localStorage 工具
├── App.tsx                     # 应用入口
├── index.css                   # 全局样式 + Tailwind
└── main.tsx                    # 渲染入口

启动方式

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

Mock 数据说明

项目预置了 12 篇示例博客文章，涵盖 React、TypeScript、前端工程化、CSS、JavaScript 五个分类。所有数据定义在：

• src/data/mockPosts.ts — 博客文章数据
• src/data/mockCategories.ts — 分类数据

Service 层封装了对这些数据的访问逻辑，模拟了异步网络请求（约 200ms 延迟）。

Markdown 上传说明

支持的文件格式

• .md
• .markdown

文件校验规则

• 文件类型必须是 Markdown（仅允许上述后缀）
• 文件大小不超过 2MB
• 文件内容不能为空

Frontmatter 支持

上传的 Markdown 文件支持可选的 YAML frontmatter：

---
title: React 工程实践总结
category: react
tags: [React, TypeScript, Vite]
summary: 这是一篇关于 React 工程实践的博客。
---

# React 工程实践总结

正文内容...

如果存在 frontmatter，上传表单会自动填充对应的字段。否则需手动填写。

上传流程

1. 选择 .md / .markdown 文件
2. 前端校验文件格式和大小
3. 读取文件内容
4. 解析可选的 frontmatter
5. 填写/确认文章信息
6. 提交后创建新文章
7. 自动跳转到新文章详情页

数据持久化

新创建的文章通过 localStorage 持久化（key: blog_posts）。刷新页面后数据依然可用。清除浏览器数据会恢复到初始 Mock 数据。

路由设计

/                           → 首页（博客列表 + 搜索 + 分类筛选）
/categories                 → 分类列表页
/categories/:categoryId     → 分类文章列表页
/posts/:postId              → 文章详情页
/upload                     → 上传新博客
*                           → 404 页面

后续可扩展方向

1. 🔍 标签筛选功能（点击标签筛选文章）
2. 🌙 深色模式
3. 📅 文章归档页（按时间归档）
4. ✏️ 本地编辑文章
5. 🗑️ 删除文章
6. 🎨 代码语法高亮（rehype-highlight）
7. 📑 Markdown 目录生成
8. 💾 localStorage 数据导入/导出
9. 📱 响应式设计优化
10. 🧪 单元测试（Vitest + Testing Library）