🌟 个人博客网站 - React + Strapi

一个现代化的个人博客/作品集网站，采用 React + TypeScript + Vite 前端技术栈和 Strapi 后端 CMS 系统构建。

🌈 特性

极简深色设计: 深色主题，克制的视觉语言
响应式布局: 在各种设备上都有良好表现
流畅动画:
- 滚动揭示动画 (Scroll Reveal)
- 导航栏滚动透明度变化
- 卡片/按钮悬停效果
类型安全: 使用 TypeScript 构建
高性能: 基于 Vite 的快速开发与构建
现代化架构: React 18 + TypeScript + Strapi Headless CMS

🚀 快速开始

前置要求

Node.js 18+
pnpm (推荐) 或 npm
Strapi 后端已搭建 (如需内容管理)

安装依赖

# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

启动开发服务器

# 启动前端开发服务器
pnpm dev

开发服务器将运行在 http://localhost:5173

后端开发服务器

# 进入后端目录
cd backend

# 启动 Strapi 后端
pnpm develop
# 或
npm run develop

Strapi 后端将运行在 http://localhost:1337/admin

📂 项目结构

blog/
├── .gitignore              # Git 忽略文件
├── LICENSE                 # 项目许可证
├── README.md               # 项目总览文档
├── package.json            # 前端项目配置
├── pnpm-lock.yaml          # 依赖锁定文件
├── tsconfig.json           # TypeScript 配置
├── vite.config.ts          # Vite 配置
├── index.html              # HTML 入口
├── src/                    # 前端源代码
│   ├── main.tsx            # 应用入口
│   ├── App.tsx             # 根组件
│   ├── App.css             # 全局样式
│   ├── components/         # 组件目录
│   │   ├── Navbar/         # 导航栏组件
│   │   ├── Hero/           # 首页 Hero
│   │   ├── Essays/         # 随笔板块
│   │   ├── Tutorials/      # 教程板块
│   │   ├── Tools/          # 工具集板块
│   │   ├── Footer/         # 页脚组件
│   │   └── ScrollReveal/   # 滚动动画包装组件
│   ├── hooks/              # React Hooks
│   ├── services/           # API 服务
│   ├── types/              # TypeScript 类型定义
│   └── utils/              # 工具函数
├── backend/                # Strapi 后端
│   ├── src/                # 后端源代码
│   ├── config/             # 配置文件
│   ├── public/             # 静态文件
│   └── package.json        # 后端项目配置
└── docs/                   # 项目文档
    ├── backend/            # 后端文档
    ├── frontend/           # 前端文档
    └── README.md           # 文档目录总览

🛠️ 项目命令

前端

命令	说明
`pnpm dev`	启动开发服务器
`pnpm build`	构建生产版本
`pnpm preview`	预览生产构建
`npm run dev`	使用 npm 启动开发服务器

后端 (进入 backend 目录)

命令	说明
`pnpm develop`	启动开发服务器 (带热重载)
`pnpm start`	启动生产服务器
`pnpm build`	构建管理面板

📚 文档导航

后端相关

前端相关

✨ 前端快速开始 (待完善)
📦 组件说明 (待完善)

🎨 设计风格

字体

标题: Playfair Display (优雅衬线)
正文: Inter (现代无衬线)

配色方案

背景: #050505 (深色)
文字: #fcfcfc (浅色)
边框: rgba(255, 255, 255, 0.08)

布局

最大宽度: 1200px
固定导航栏: 80px
响应式网格系统

🔄 开发流程

1. 前端开发

# 启动前端开发服务器
pnpm dev

# 在浏览器中访问 http://localhost:5173

2. 后端开发

# 进入后端目录
cd backend

# 启动 Strapi 后端
pnpm develop

# 在浏览器中访问 http://localhost:1337/admin

3. API 集成

前端通过 REST API 从 Strapi 后端获取内容数据。详见前端集成指南

🌐 部署

前端部署

构建生产版本并部署到静态托管服务 (如 Vercel, Netlify, GitHub Pages):

pnpm build

构建产物将输出到 dist/ 目录

后端部署

Strapi 可以部署到多种云平台 (如 Railway, Heroku, AWS, DigitalOcean):

cd backend
pnpm build
pnpm start

详见 Strapi 部署文档

📝 内容类型

项目包含 4 个主要内容类型：

Essays (随笔) - 8 个字段
Tutorials (教程) - 10 个字段
Tools (工具集) - 6 个字段
Comments (评论) - 7 个字段 + 关系

🛣️ 下一步

添加单元测试 (vitest + react-testing-library)
配置 CI/CD (GitHub Actions)
文章详情页 + 路由
实现全站搜索功能
评论提交表单
添加暗色/亮色主题切换
Sitemap + SEO 优化
Vercel / Netlify 一键部署配置

完整的开发待办见 todolist.md。

🧰 配套子项目

mini-tools/ —— 一组纯前端单文件 HTML 小工具，与博客主站独立，离线可用：

PDF：合并 / 拆分 / 图片转 PDF
图片：压缩、格式互转（JPG/PNG/WebP）
数据：JSON 格式化、CSV↔JSON、Markdown→HTML、Base64
实用：二维码生成、字数统计、时间戳转换

入口：mini-tools/index.html · 双击文件即可使用，所有处理都在本地浏览器中完成。

📜 迭代记录

2026-05-22 · V3 · `mini-tools/` 子项目：11 个办公小工具

在主项目仓库内新增 mini-tools/ 目录，全部为单文件 HTML，纯前端、无后端，离线可用。与博客主站设计风格一致（暗色极简、Playfair Display + Inter）。

文件转换

pdf-merger.html · 多 PDF 合并（pdf-lib）
pdf-splitter.html · PDF 按页码范围拆分
image-to-pdf.html · 图片转 PDF（A4 / Letter / 原图、横竖向、边距）
image-compressor.html · 图片压缩与 JPG/PNG/WebP 互转（Canvas + JSZip 批量打包）

文本与数据

json-formatter.html · 格式化 / 压缩 / 校验（带行列号）
csv-json.html · CSV ↔ JSON 双向转换（手写解析器，处理引号转义）
markdown-html.html · 实时预览 + 导出 HTML（marked + DOMPurify）
base64.html · 文本 + 文件双向编解码（Unicode 安全）

日常实用

qrcode.html · 二维码生成（尺寸、纠错级、配色）
word-counter.html · 中英文字数 + 阅读时长
timestamp.html · Unix 时间戳 ↔ 日期（含时区）

入口与文档

mini-tools/index.html 汇总主页（按文件转换 / 数据 / 实用三组分类）
mini-tools/README.md 使用说明

总计 12 个 HTML 文件，共 ~2660 行，全部自包含可双击直接打开。

2026-05-22 · V2 大版本：路由 + 详情页 + 搜索 + 主题 + 评论 + SEO + 测试 + CI

本次扩展把项目从"前后端能跑通"升级到"接近成品"水平，仍然不改动任何原有 CSS Module。

路由与详情页

引入 react-router-dom@7 与 react-helmet-async
新增 src/pages/：HomePage、EssayDetail、TutorialDetail
App.tsx 改用 <BrowserRouter> + <Routes> 顶层路由
<ScrollToTop>：路由切换自动回顶部 / 命中 hash 滚动到锚点
Navbar 在详情页智能切换为 <Link to="/#xxx">，回首页后自动滚动
Essays/Tutorials 列表卡片改用 <Link>，整页不刷新

主题切换

ThemeContext + useTheme，localStorage 持久化
右下角浮动 ThemeToggle
浅色主题通过 :root[data-theme="light"] 选择器追加，默认深色不变

站内搜索

浮动 SearchBar 按钮 + 全屏对话框，Ctrl/Cmd + K 快捷键
客户端跨随笔/教程/工具过滤

评论系统

api.getCommentsByEssay / api.postComment
<Comments> 组件嵌入 EssayDetail 底部
友好处理 Strapi Public 角色未开放写权限的情况

SEO

<Helmet> 动态 title / description / og:*
scripts/generate-sitemap.mjs 拉取 Strapi 内容生成 dist/sitemap.xml
public/robots.txt

测试基建

vitest 1.6 + @testing-library/react + jsdom
测试覆盖 transformData、useApiFetch、services/api —— 23 个测试全部通过
pnpm test / pnpm test:run / pnpm test:coverage

CI/CD + 部署

.github/workflows/ci.yml：typecheck + build + test
vercel.json 与 netlify.toml：SPA fallback + 环境变量提示
docs/deployment/ 四篇部署文档（Vercel / Netlify / Railway / Render）
.github/PULL_REQUEST_TEMPLATE.md + ISSUE_TEMPLATE/

新增教程文字稿

docs/tutorials/04-routing-and-detail-pages.md (~10k 字)
docs/tutorials/05-deploy-to-production.md (~9.5k 字)

新增 package.json 脚本

命令	说明
`pnpm test`	启动 vitest watch 模式
`pnpm test:run`	单次跑完所有测试
`pnpm test:coverage`	生成覆盖率报告
`pnpm typecheck`	`tsc --noEmit`
`pnpm sitemap`	生成 dist/sitemap.xml
`pnpm ci`	本地复现 CI（install + typecheck + test + build）

验收

✅ pnpm typecheck 通过
✅ pnpm test:run 23/23 通过
✅ pnpm build 成功（CSS 16.94 kB / JS 257.67 kB）
✅ 前后端仍同时在 5173 / 1337 运行
✅ 原有 CSS Module 文件零修改，主页视觉完全保持

2026-05-22 · V1 · 项目搭建完善

目标：在不改动前端视觉样式的前提下，把项目搭建完善起来。

Push & 备份

将工作区前后端 API 接入相关改动一次性提交并推送到 origin/main， commit: chore: 同步前后端 API 接入与内容类型 schema 更新

启动与连通性

新增 scripts/check-ports.mjs：启动前自动检查 5173 / 1337 端口可用性
根 package.json 增加脚本：check:ports、predev（自动前置检查）、backend:dev、backend:seed
验证后端在 1337 启动成功，API /api/tutorials 返回 200
验证前端在 5173 启动成功

内容补全（教程文字稿等）

新增 docs/tutorials/ 三篇完整教程文字稿：
- 01-react-vite-setup.md · React + Vite + TypeScript 项目初始化
- 02-strapi-headless-cms.md · Strapi 5 Headless CMS 接入
- 03-frontend-backend-integration.md · 前后端联调实战
新增 docs/essays/ 三篇随笔示例（克制 / 手艺与代码 / 工具与心智）
新增 docs/tools/README.md 工具卡片说明
新增 backend/scripts/seed.js 一键灌入示例数据的种子脚本
更新 docs/README.md 加入教程 / 随笔 / 工具索引

工程化（不改前端 UI）

增强 .env.example，区分前端 / 后端环境变量说明，加入种子 Token 选项
src/services/api.ts 新增 ping() 健康检查方法（不影响 UI）
src/hooks/useApiFetch.ts 已采用 useRef 持有最新 fetchFn，避免重复请求
全程未改动任何 CSS Module 文件，前端样式保持原样

文档

新增 todolist.md 记录全部开发计划与未来路线
本 README.md 加入迭代记录章节

历史

提交	说明
9a7c2f0	前端接入后端 API 接口
d7f5ca6	将 backend 从 submodule 改为常规目录
54b0699	first commit

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

👨‍💻 开发者

技术选型: React + TypeScript + Vite + Strapi
字体: Playfair Display + Inter (Google Fonts)
设计灵感: 极简深色风格

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.claude		.claude
.github		.github
backend		backend
docs		docs
mini-tools		mini-tools
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
blog.html		blog.html
index.html		index.html
netlify.toml		netlify.toml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
todolist.md		todolist.md
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts
快速开始后端搭建.txt		快速开始后端搭建.txt

Folders and files

Latest commit

History

Repository files navigation