1. 项目概述与背景最近在整理自己的开源项目时我决定把几年前做的一个老项目“如何月HUB”正式归档并写篇文章记录一下它的始末。这个项目本质上是一个基于React和TypeScript的东方Project二次创作同人网站主要展示“如何月”这个角色的相关内容。虽然现在看代码有些稚嫩架构也谈不上多优雅但它是我从纯前端转向全栈开发、学习现代Web工具链的一个关键里程碑。项目已经停止维护并迁移到了新的“如何月ポータル”但回过头看里面涉及的很多技术选型和开发思路特别是如何用Vite、React 18和TypeScript搭建一个现代的单页应用对很多刚入门的朋友来说依然有不错的参考价值。简单来说这是一个典型的个人兴趣驱动的技术实践项目。它不追求大而全而是聚焦于如何用一套当时还算前沿的技术栈React TypeScript Vite快速构建一个风格统一、体验流畅的静态内容站点。过程中我踩了不少坑也积累了一些关于组件设计、状态管理和构建优化的心得。如果你正在学习React生态或者想用Vite启动一个自己的Side Project那么我在这项目里趟过的路或许能帮你避开一些弯路。2. 技术栈选型与架构思路2.1 为什么是React TypeScript Vite2019年前后我决定重写这个站点时前端生态正处在一个微妙的节点。Create React App (CRA) 依然是主流但Webpack的构建速度在项目稍大时就开始让人焦虑。Vite 1.x刚出现其基于ES Module的闪电般冷启动和热更新速度让我眼前一亮。对于个人项目快速验证想法、即时看到改动效果至关重要Vite完美契合了这个需求。它原生支持TypeScript和JSX配置极其简单几乎开箱即用这让我能更专注于业务逻辑而非构建配置。选择TypeScript而非纯JavaScript则是出于项目可维护性的长远考虑。即使是一个人开发的小项目清晰的类型定义也能极大减少运行时错误尤其是在处理东方Project复杂的角色、作品数据关系时。TypeScript的接口Interface和类型别名Type Alias能很好地定义数据模型配合React的组件Props类型检查代码的健壮性提升了一个档次。虽然初期学习曲线稍陡但带来的开发体验和代码提示的收益是巨大的。React的选择则更顺理成章。其组件化思想非常适合构建这种由多个独立内容区块如角色介绍、作品列表、画廊组成的页面。当时React Hooks已经稳定函数式组件加上Hooks的写法让逻辑复用和状态管理变得非常清爽不再需要面对Class组件中令人头疼的this绑定和生命周期方法。2.2 项目结构与职责划分项目的目录结构遵循了当时社区比较推崇的按功能模块划分的方式而不是传统的按文件类型components, pages, utils划分。这更贴合React“组件即一切”的理念。src/ ├── assets/ # 静态资源图片、字体、样式 ├── components/ # 通用共享组件Button, Card, Layout │ ├── common/ # 纯UI组件无业务逻辑 │ └── features/ # 业务功能组件如Gallery, MusicPlayer ├── features/ # 业务功能模块 │ ├── character/ # 角色介绍相关逻辑、组件、类型定义 │ ├── works/ # 作品列表模块 │ └── gallery/ # 图片画廊模块 ├── hooks/ # 自定义React Hooks ├── lib/ # 第三方库封装或工具函数 ├── pages/ # 页面级组件对应路由 ├── styles/ # 全局样式与CSS模块 ├── types/ # 全局TypeScript类型定义 └── main.tsx # 应用入口这种结构的核心思想是“高内聚、低耦合”。所有与“角色介绍”相关的东西——组件、工具函数、类型定义、甚至模拟数据——都放在features/character目录下。当需要修改或删除这个功能时影响范围非常清晰不会散落在项目的各个角落。components/目录下存放的是真正可复用的、与业务无关的“砖块”比如按钮、卡片、模态框等。注意这种“Feature-based”结构在项目初期功能较少时可能显得有些“重”但随着功能模块增加其维护优势会越来越明显。如果你的项目非常小只有2-3个页面从简单的“按类型划分”开始也未尝不可但最好心里有这根弦为未来的扩展留好余地。2.3 状态管理轻量化的选择对于这个项目我没有引入Redux、MobX这类重型状态管理库。原因很简单状态复杂度不高。大部分状态都是组件内部的UI状态如模态框是否打开、下拉菜单是否展开或者可以通过Props向下传递的数据。少量需要跨组件共享的状态我使用了React Context API结合useReducerHook。例如全局的主题深色/浅色模式和用户的语言偏好。Context能解决“Prop Drilling”属性层层传递的问题而useReducer提供了比useState更结构化的状态更新方式尤其适合状态逻辑较复杂的场景。// 示例主题Context interface ThemeState { mode: light | dark; } const ThemeContext React.createContext{ state: ThemeState; dispatch: React.DispatchAction; } | undefined(undefined); function themeReducer(state: ThemeState, action: Action): ThemeState { switch (action.type) { case TOGGLE_THEME: return { mode: state.mode light ? dark : light }; default: return state; } } export function ThemeProvider({ children }: { children: React.ReactNode }) { const [state, dispatch] useReducer(themeReducer, { mode: light }); return ( ThemeContext.Provider value{{ state, dispatch }} {children} /ThemeContext.Provider ); }实操心得不要盲目引入状态管理库。先仔细分析你的应用状态。如果大部分是局部状态用useState如果需要跨少量组件共享用Context只有当应用变得非常庞大存在大量异步逻辑和复杂的中间件需求时才考虑Redux Toolkit这类方案。过早优化是万恶之源。3. 核心功能模块实现解析3.1 基于文件系统的路由与懒加载项目使用react-router-domv6进行路由管理。为了保持结构清晰路由定义集中在一个文件中并且与pages/目录下的组件一一对应。一个关键优化是利用了Vite和React.lazy实现的动态导入懒加载。// router.tsx import { lazy, Suspense } from react; import { createBrowserRouter } from react-router-dom; // 使用lazy进行代码分割 const HomePage lazy(() import(./pages/Home)); const CharacterPage lazy(() import(./pages/Character)); const WorksPage lazy(() import(./pages/Works)); const router createBrowserRouter([ { path: /, element: ( // Suspense提供加载中的回退UI Suspense fallback{GlobalLoadingSpinner /} Layout / {/* 公共布局组件 */} /Suspense ), children: [ { index: true, element: HomePage / }, { path: character/:id, element: CharacterPage / }, { path: works, element: WorksPage / }, ], }, ]); // main.tsx import { RouterProvider } from react-router-dom; ReactDOM.createRoot(document.getElementById(root)!).render( React.StrictMode RouterProvider router{router} / /React.StrictMode );这样做的好处是初始加载的JavaScript包体积很小只有当前页面所需的代码。当用户点击导航到“作品列表”页面时才会动态加载WorksPage组件的代码。这在内容较多的站点上对首屏加载速度的提升非常显著。Vite在背后会自动进行代码分割。踩坑记录使用React.lazy时必须用Suspense组件包裹并提供fallback。否则在组件加载期间页面会是一片空白。fallback可以是一个简单的加载动画组件。另外懒加载的组件必须是export default导出的。3.2 数据获取与静态内容渲染作为一个同人资料站大部分内容角色介绍、作品信息是相对静态的。我最初尝试了直接从Markdown文件读取内容并渲染的方案。具体做法是将内容写在.md或.mdx文件中利用Vite插件如vite-plugin-md在构建时将其转换为React组件或JSON数据。// 1. 配置vite.config.ts import Markdown from vite-plugin-md; export default defineConfig({ plugins: [ React(), Markdown(), // 处理.md文件 ], }); // 2. 直接导入.md文件 import CharacterIntro from ../data/character-intro.md?raw; // Vite的raw导入 // 3. 使用一个Markdown渲染组件例如react-markdown import ReactMarkdown from react-markdown; function CharacterPage() { return ( article ReactMarkdown{CharacterIntro}/ReactMarkdown /article ); }这种方式将内容和代码分离非技术人员也能通过修改Markdown文件来更新网站内容非常友好。而且由于内容在构建时就已经确定可以直接生成静态HTML对SEO和加载速度都极有益处。注意事项如果内容需要支持富文本或自定义组件可以考虑使用MDXMarkdown JSX。它允许你在Markdown中直接使用React组件灵活性更高但配置也稍复杂一些。对于纯内容展示react-markdown库足够轻量且高效。3.3 图片画廊的性能优化“画廊”模块展示如何月的相关图片这是前端性能的一个常见挑战。我主要做了以下几方面优化图片格式与压缩将所有图片转换为现代格式WebP并在不损失视觉质量的前提下进行压缩。我使用了构建脚本在npm run build时自动调用sharp库批量处理src/assets/images目录下的图片并输出到dist目录。WebP格式通常比同质量的JPEG或PNG小25%-35%。懒加载Lazy Loading使用原生img loadinglazy /属性或者Intersection Observer API实现自定义懒加载。这样只有当图片滚动到视口附近时才开始加载减少了初始页面的网络请求和内存占用。响应式图片Responsive Images针对不同屏幕尺寸和分辨率提供不同尺寸的图片源。使用picture元素和srcset属性。// 一个优化后的图片组件示例 interface OptimizedImageProps { src: string; alt: string; width: number; height: number; } function OptimizedImage({ src, alt, width, height }: OptimizedImageProps) { const webpSrc src.replace(/\.(jpg|png)$/, .webp); return ( picture {/* 优先提供WebP格式 */} source srcSet{webpSrc} typeimage/webp / {/* 兼容性回退 */} source srcSet{src} type{image/${src.split(.).pop()}} / img src{src} alt{alt} width{width} height{height} loadinglazy style{{ maxWidth: 100%, height: auto }} // 保持宽高比 / /picture ); }虚拟列表Virtual List当画廊图片数量非常多比如上百张时一次性渲染所有DOM节点会导致严重的性能问题。我引入了react-window库实现虚拟列表。它只渲染可视区域内的图片元素大幅提升了滚动流畅度。实操心得图片优化是前端性能提升的“低垂果实”投入产出比很高。建议在项目初期就建立图片处理流程。可以使用像vite-plugin-imagemin这样的插件在构建时自动压缩或者将图片托管到支持自动格式转换和尺寸裁剪的CDN服务上。4. 开发体验与工程化配置4.1 基于Vite的极致开发体验Vite的开发服务器基于原生ESM启动速度极快。我的项目冷启动时间在1秒以内热更新HMR几乎在保存文件的同时就能在浏览器中反映出来这种流畅感是Webpack时代难以想象的。vite.config.ts的配置也非常简洁明了。// vite.config.ts import { defineConfig } from vite; import react from vitejs/plugin-react; import path from path; export default defineConfig({ plugins: [react()], resolve: { alias: { : path.resolve(__dirname, ./src), // 配置路径别名方便导入 }, }, server: { port: 3000, open: true, // 启动后自动打开浏览器 }, build: { outDir: dist, sourcemap: true, // 生产环境生成sourcemap方便调试 rollupOptions: { output: { // 对chunk文件进行更好的命名便于缓存 manualChunks(id) { if (id.includes(node_modules)) { return vendor; } }, }, }, }, });路径别名的配置强烈推荐。它让导入语句从../../../components/Button变成了/components/Button代码清爽了很多移动文件时也不必再手动修改一堆相对路径。4.2 TypeScript的严格模式与ESLint/Prettier为了保持代码质量我开启了TypeScript最严格的检查选项tsconfig.json中的strict: true并配合ESLint和Prettier进行代码规范和格式化。// tsconfig.json 核心配置 { compilerOptions: { target: ES2020, useDefineForClassFields: true, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, skipLibCheck: true, moduleResolution: bundler, allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true, noEmit: true, jsx: react-jsx, strict: true, // 开启所有严格类型检查 noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true, baseUrl: ., paths: { /*: [./src/*] // 配合Vite别名 } }, include: [src], references: [{ path: ./tsconfig.node.json }] }在package.json中配置脚本可以在提交代码前自动检查和格式化。scripts: { dev: vite, build: tsc vite build, lint: eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0, prettier: prettier --write \src/**/*.{ts,tsx,css,md}\, pre-commit: npm run lint npm run prettier }踩坑记录strict: true一开始会报很多类型错误让人有点抓狂但请坚持下去。它强迫你写出类型安全的代码从长远看节省了大量的调试时间。对于第三方库缺乏类型定义的情况可以创建src/types/目录来存放自定义的类型声明文件.d.ts。4.3 样式方案CSS Modules与CSS-in-JS的取舍项目中我主要使用了CSS Modules。它的好处是样式默认局部作用避免了全局污染同时写法又和原生CSS一样学习成本低。Vite原生支持CSS Modules只需将文件命名为*.module.css即可。/* Button.module.css */ .primary { background-color: #007bff; color: white; padding: 0.5rem 1rem; border: none; border-radius: 4px; } .primary:hover { background-color: #0056b3; }// Button.tsx import styles from ./Button.module.css; interface ButtonProps extends React.ButtonHTMLAttributesHTMLButtonElement { variant?: primary | secondary; } export function Button({ variant primary, className, ...props }: ButtonProps) { const variantClass variant primary ? styles.primary : styles.secondary; return button className{${variantClass} ${className || }} {...props} /; }我也尝试了styled-components这类CSS-in-JS方案它确实非常灵活可以将样式直接写在组件文件中并且能轻松地基于props动态调整样式。但考虑到这是一个内容为主的静态站点我更看重的是可缓存性和构建速度。CSS Modules生成的静态CSS文件可以被浏览器缓存而CSS-in-JS的样式通常在运行时注入可能会影响首屏渲染速度虽然新版本有优化。最终为了更稳定的性能和更简单的架构我选择了CSS Modules。注意样式方案没有绝对的好坏只有是否适合。如果你的项目有大量动态主题、样式需要频繁根据状态变化CSS-in-JS可能是更好的选择。对于偏展示型、追求极致性能的站点CSS Modules或Utility-First的Tailwind CSS更值得考虑。5. 部署与持续集成5.1 静态站点托管选择由于项目是纯静态的构建后生成dist目录包含HTML、CSS、JS和资源文件托管选择非常多。我最终选择了Vercel原因如下无缝的Git集成连接GitHub仓库后每次git push到主分支都会自动触发部署。极快的全球CDN生成的站点被部署到全球边缘网络访问速度快。自定义域名和HTTPS免费提供配置简单。预览部署针对每个Pull Request生成独立的预览URL方便团队评审。部署配置极其简单基本上就是“零配置”。Vercel会自动检测到这是一个Vite React项目并运行npm run build进行构建。替代方案Netlify是另一个非常优秀的同类平台功能类似。如果你更喜欢自己掌控可以将dist目录上传到任何对象存储服务如AWS S3、Google Cloud Storage或Cloudflare R2然后配置CDN和域名即可。5.2 自动化工作流利用GitHub Actions我设置了一个简单的CI持续集成流程在每次推送代码时自动运行测试如果有的话和代码检查。# .github/workflows/ci.yml name: CI on: [push, pull_request] jobs: lint-and-test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 cache: npm - name: Install Dependencies run: npm ci # 使用ci命令确保依赖锁一致 - name: Run Linter run: npm run lint # - name: Run Tests # run: npm test - name: Build Project run: npm run build这个流程能及早发现代码风格问题和构建错误避免有问题的代码被合并到主分支。对于个人项目这或许不是必须的但它培养了一种良好的工程习惯。6. 项目复盘与迁移至“如何月ポータル”6.1 为何停止维护并启动新项目“如何月HUB”运行了几年后我逐渐发现了它的几个局限性架构僵化早期的技术选型和代码结构在应对新需求时显得不够灵活。例如想增加一个用户评论功能就需要大动干戈。技术债一些早期为了快速实现而写的“临时方案”变成了“永久方案”代码可读性下降。内容管理不便虽然用Markdown管理内容但每次更新都需要重新构建和部署对于非技术运营者不够友好。因此我决定启动“如何月ポータル”项目。新项目在技术栈上进行了升级如使用了Next.js App Router引入了更规范的状态管理但更重要的是架构理念的转变从“静态内容站”转向了“动态内容门户”。新项目计划接入一个Headless CMS内容管理系统让内容更新可以通过后台界面完成无需触碰代码。同时设计上更注重交互性和社区功能。6.2 从旧项目迁移的经验教训迁移过程并非重写所有代码而是有策略地复用和重构。资产迁移图片、字体等静态资源可以直接复制到新项目。组件重构对于UI组件如Button、Card我评估了其设计是否过时、API是否合理。设计良好的组件直接复制有问题的则利用这个机会用更新的模式如Compound Components重写。逻辑抽取将旧项目中的工具函数、自定义Hooks、类型定义仔细审查并迁移。这是一个清理技术债的好机会可以统一代码风格补充单元测试。数据迁移将Markdown文件中的内容通过脚本批量转换为新CMS所需的数据格式如JSON然后导入。这个过程让我深刻体会到设计系统和清晰的模块边界的重要性。如果旧项目的组件从一开始就设计良好、职责单一迁移成本会低得多。7. 给后来者的建议回顾整个“如何月HUB”项目它是我前端学习之路上的一个扎实的脚印。如果你也想启动一个类似的技术实践项目我的建议是不要过度设计但要为变化留好接口。项目初期你无法预知所有未来需求。选择一个你熟悉且能快速上手的栈比如Vite React先做出一个可用的版本。但在设计组件和模块时要有意识地思考“如果这里以后要改会不会很麻烦”。良好的命名、单一职责、清晰的Props接口这些简单的原则能极大提升代码的适应能力。性能优化要有节奏。不要一开始就追求极致的性能。先保证功能正确、用户体验流畅。在项目有一定规模后再用Lighthouse等工具进行性能测评有针对性地优化瓶颈如图片、包体积、渲染性能。记住“过早优化是万恶之源”。文档和注释不是可选项。即使是个人项目也请为复杂的逻辑、重要的决策点写下注释。几个月后你自己也会忘记当时为什么这么写。如果项目开源清晰的README和代码注释是吸引贡献者的第一步。享受过程而不仅仅是结果。个人项目最大的价值在于学习。大胆尝试新技术踩坑然后爬出来。把“如何月HUB”归档我没有任何遗憾因为它已经完成了它的使命让我学到了东西并成为了下一个更好项目的基石。