react-vite-expert

React + Vite 专家

概述

成为 React + Vite 专家，深入掌握现代 React 开发模式、最优项目组织方式、性能优化技巧以及适用于生产环境的配置。本技能提供使用 Vite 作为构建工具来构建快速、易维护且可扩展的 React 应用所需的一切。

核心能力

1. 项目架构与组织

指导用户构建 React 应用，最大限度提升可维护性和可扩展性。

参考：references/project_architecture.md

这份全面的指南涵盖：

• 文件夹结构模式：按功能划分、原子化设计、领域驱动设计
• 文件组织：就近放置策略、命名规范
• 导入策略：路径别名、聚合导出、摇树优化
• 状态管理组织：局部状态与全局状态，以及状态的存放位置
• 扩展指南：应用增长时如何调整结构

适用场景：

• 用户询问“我应该如何组织 React 项目？”
• 启动新项目
• 重构现有项目结构
• 应用变得难以导航
• 需要建立团队规范

关键决策树：

1. 按功能划分还是按组件划分：阅读“最优文件夹结构”一节
2. 状态管理策略：阅读“状态管理策略”一节
3. 导入组织方式：阅读“导入策略”一节

2. 代码生成与脚手架

使用适用于生产环境的模板，自动创建组件、Hook 和功能模块。

可用脚本：

scripts/create_component.py 生成包含所有必要文件的完整组件：

• 组件文件（.tsx）
• TypeScript 类型（.types.ts）
• CSS Module（.module.css）
• 测试（.test.tsx）
• Storybook story（.stories.tsx）[可选]
• 用于简洁导入的索引文件

# Create a basic component
python scripts/create_component.py Button --type component

# Create a page component with lazy loading
python scripts/create_component.py Dashboard --type page

# Create component with children prop
python scripts/create_component.py Card --children

# Create component with Storybook story
python scripts/create_component.py Button --story

# Without tests
python scripts/create_component.py SimpleComponent --no-tests

适用场景：

• 创建任何新组件
• 设置新的功能模块
• 需要统一的组件结构
• 希望加快开发速度

scripts/create_hook.py 使用常见模式的模板生成自定义 Hook：

• 状态管理 Hook
• Effect Hook
• 数据获取 Hook
• LocalStorage Hook
• 防抖 Hook
• 定时器 Hook

# Create custom hook
python scripts/create_hook.py useAuth --type custom

# Create data fetching hook
python scripts/create_hook.py useUserData --type fetch

# Create localStorage hook
python scripts/create_hook.py useSettings --type localStorage

# Create debounce hook
python scripts/create_hook.py useSearchDebounce --type debounce

适用场景：

• 提取可复用逻辑
• 创建自定义状态管理
• 需要常见的 Hook 模式
• 希望自动生成带测试的 Hook

3. 性能优化

优化 React 应用，以实现最高性能和最小的打包体积。

参考：references/performance_optimization.md

本指南涵盖：

• React 渲染优化：React.memo()、useMemo()、useCallback()
• 代码拆分：React.lazy()、基于路由的拆分、组件拆分
• 虚拟化：使用 react-window 优化长列表
• 防抖与节流：输入优化、滚动处理
• Vite 构建优化：代码块拆分、压缩、压缩传输
• 图像优化：WebP/AVIF、延迟加载、自适应图像
• 网络优化：API 请求优化、预取
• CSS 性能：CSS Modules 与 CSS-in-JS 的比较、关键 CSS
• Web Vitals 跟踪：测量 LCP、FID、CLS

适用场景：

• 应用感觉运行缓慢或卡顿
• 打包体积较大
• 初始加载时间较长
• 用户询问优化相关问题
• 准备部署到生产环境
• 性能审计发现问题

快速性能检查清单：

1. 运行 python scripts/analyze_bundle.py，找出体积较大的依赖
2. 查看 references/performance_optimization.md 中的优化策略
3. 为路由应用代码拆分：React.lazy(() => import('./Page'))
4. 使用记忆化优化开销较大的组件：React.memo(Component)
5. 使用 useMemo() 优化开销较大的计算
6. 为长列表实现虚拟化（react-window）
7. 优化图像（WebP、延迟加载）
8. 检查 assets/vite.config.optimized.ts 中的 Vite 配置

scripts/analyze_bundle.py 分析构建输出并提供优化建议：

# Run bundle analysis
python scripts/analyze_bundle.py

分析内容：

• package.json 依赖（识别体积较大的库）
• 导入模式（建议更适合摇树优化的导入方式）
• 构建输出（打包体积、代码块分布）
• 提供具体的优化建议

运行时机：

• 部署到生产环境之前
• 添加新依赖之后
• 打包体积意外增大时
• 每月定期审计
• 性能优化阶段

4. 生产就绪配置

部署经过优化的 Vite 配置和项目设置。

可用资源：

assets/vite.config.optimized.ts 经过全面优化的 Vite 配置，包含：

• 路径别名：简洁的导入方式（@/components、@/hooks 等）
• 手动拆分代码块：按供应商和功能拆分代码块，以便更好地缓存
• 压缩：使用 Terser，并在生产环境中移除 console.log
• 打包分析器：可视化打包内容
• 资源优化：图片处理、字体加载
• 开发代理：API 代理配置
• 源映射：按条件生成源映射
• CSS 代码拆分：自动拆分 CSS 代码块

适用场景：

• 启动新项目
• 优化现有构建
• 设置生产环境流水线
• 需要更好的缓存策略
• 想要分析打包内容

使用方法：

1. 将 assets/vite.config.optimized.ts 复制到项目根目录
2. 安装依赖：npm install -D rollup-plugin-visualizer
3. 根据你的功能自定义手动拆分的代码块
4. 使用分析器运行构建：npm run build:analyze

assets/tsconfig.optimized.json TypeScript 配置，包含：

• 启用严格模式：在编译时发现更多错误
• 路径别名：与 Vite 配置保持一致
• 优化的编译器选项：适用于 Vite 和现代 React
• 未使用代码检测：noUnusedLocals、noUnusedParameters
• 类型安全：noImplicitReturns、noUncheckedIndexedAccess

适用场景：

• 启动新的 TypeScript 项目
• 需要更严格的类型检查
• 需要路径别名
• 提升类型安全性

assets/package.json.example 完整的 package.json，包含：

• 所有推荐脚本：dev、build、test、lint、format
• 必备依赖项：React、React DOM、Router
• 开发依赖项：TypeScript、ESLint、Prettier、Vitest
• 推荐的可选依赖项：按使用场景分类
• Husky 和 lint-staged 配置：提交前钩子
• CI/CD 脚本：用于自动化流水线

适用场景：

• 启动新项目
• 需要脚本建议
• 设置 CI/CD
• 想要使用 Git 钩子
• 需要 package 参考

assets/project-structure-example.md 完整的项目结构，包含：

• 完整目录树：基于功能的架构
• 关键文件示例：App.tsx、路由器、提供程序、API 设置
• 配置示例：vitest、eslint、prettier
• 测试设置：测试工具和模拟对象
• 扩展指南：如何扩展项目结构

适用场景：

• 从头启动新项目
• 需要结构参考
• 重构现有项目
• 向团队讲解组织方式
• 创建项目模板

5. React 最佳实践与模式

采用现代 React 模式，避免常见陷阱。

参考：references/best_practices.md

本指南涵盖：

• 组件模式：复合组件、渲染属性、高阶组件、自定义钩子
• TypeScript 最佳实践：为组件、钩子、事件和泛型组件添加类型
• 错误处理：错误边界、异步错误处理
• 表单处理：受控组件、验证、表单库
• 测试：组件测试、钩子测试、模拟
• 常见反模式：应避免的做法及原因
• 无障碍访问：a11y 最佳实践、ARIA、键盘导航

查阅时机：

• 实现复杂的组件模式
• 需要 TypeScript 指导
• 设置错误处理
• 创建表单
• 编写测试
• 用户询问“……的最佳做法是什么？”
• 代码审查请求
• 讲解 React 模式

模式选择指南：

• 复合组件：适用于灵活、可组合的 UI（标签页、手风琴）
• 自定义钩子：提取并复用逻辑（useAuth、useDebounce）
• Context + Hook：在组件树中共享状态（主题、身份验证）
• 渲染属性：通过渲染控制共享代码（较少使用，大多已被钩子取代）
• 高阶组件：添加横切关注点（较少使用，大多已被钩子取代）

6. TypeScript 精通

使用恰当的 TypeScript 模式编写类型安全的 React 代码。

references/best_practices.md 中的关键 TypeScript 模式：

• 组件属性类型（接口与类型）
• 事件处理程序类型
• Ref 类型
• 泛型组件类型
• Hook 类型
• 类型守卫与类型收窄
• 工具类型

用户询问 TypeScript 时：

1. 阅读 references/best_practices.md 中的相关部分
2. 提供类型安全的示例
3. 解释采用此模式的原因
4. 同时展示错误和正确的写法

常见的 TypeScript 问题：

• “如何为这个组件添加类型？” → 组件属性类型部分
• “如何为事件处理程序添加类型？” → Hook 类型部分
• “如何创建泛型组件？” → 泛型组件部分
• “如何为 ref 添加类型？” → Hook 类型部分

7. 测试策略

为 React 应用实施全面的测试。

references/best_practices.md 中的测试模式：

• 使用 React Testing Library 测试组件
• 测试自定义 Hook
• 测试工具与设置
• 模拟策略
• 集成测试

测试理念：

• 测试用户行为，而非实现细节
• 测试用户看到和执行的内容
• 模拟外部依赖
• 使用描述性测试名称
• 遵循 Arrange-Act-Assert 模式

用户需要测试方面的帮助时：

1. 检查组件生成器是否创建了测试：scripts/create_component.py
2. 参考 references/best_practices.md 中的测试部分
3. 在 assets/project-structure-example.md 中查看测试设置
4. 针对用户的使用场景提供具体测试示例

8. 状态管理指南

选择并实施合适的状态管理解决方案。

状态管理决策树（来自 references/project_architecture.md）：

Is it server data (from API)?
└─ Yes → TanStack Query (React Query)

Is it local to a component?
└─ Yes → useState

Is it shared between 2-3 components?
└─ Yes → Lift state up (props)

Is it global but simple (theme, auth)?
└─ Yes → Context + useState

Is it global and complex?
├─ Small/medium app → Zustand
└─ Large app with complex async → Redux Toolkit

需要参考 references/project_architecture.md 的情况：

• 选择状态管理解决方案
• 需要各种方案的代码示例
• 了解权衡取舍
• 迁移状态管理方案
• 重渲染导致的性能问题

工作流示例

示例 1：“帮我用最佳实践启动一个新的 React 项目”

1. 了解需求：

   • 询问：项目规模、功能、状态需求、团队规模
   • 确定：要使用哪些模式、结构的复杂程度

2. 提供结构：

   • 展示 assets/project-structure-example.md
   • 说明基于功能的架构与更简单的架构
   • 根据项目规模给出建议

3. 设置配置：

   • 复制 assets/vite.config.optimized.ts
   • 复制 assets/tsconfig.optimized.json
   • 参考 assets/package.json.example 中的脚本

4. 生成初始组件：

   # Create basic UI components
   python scripts/create_component.py Button --type component --story
   python scripts/create_component.py Input --type component
   
   # Create pages
   python scripts/create_component.py HomePage --type page
   
   # Create hooks
   python scripts/create_hook.py useAuth --type custom
   

5. 说明后续步骤：

   • 设置 git hooks（husky）
   • 配置 ESLint 和 Prettier
   • 设置测试
   • 创建初始路由

示例 2：“我的 React 应用运行很慢，该如何优化？”

1. 分析当前状态：

   # Run bundle analyzer
   python scripts/analyze_bundle.py
   

2. 查看分析结果：

   • 找出体积较大的依赖
   • 检查是否存在重复项
   • 检查导入模式

3. 参考优化指南：

   • 阅读 references/performance_optimization.md
   • 根据分析结果重点查看相关部分

4. 实施优化（按影响从大到小排序）：

   • 代码拆分：为路由实现延迟加载
   • 移除体积较大的依赖：建议使用更轻量的替代方案
   • 记忆化：为开销较大的组件添加 React.memo()
   • 虚拟化：适用于渲染长列表的情况
   • 图片优化：实现延迟加载，使用 WebP 格式
   • 构建优化：应用 assets/vite.config.optimized.ts

5. 衡量改进效果：

   • 分别在优化前后运行构建
   • 比较包体积
   • 测试 Web Vitals

示例 3：“我应该如何组织不断扩大的 React 项目？”

1. 评估当前规模：

   • 询问：有多少个组件？有多少项功能？
   • 确定：当前的痛点

2. 参考架构指南：

   • 阅读 references/project_architecture.md
   • 章节：“Optimal Folder Structure”

3. 推荐结构：

   • 小型（<10 个组件）：扁平结构
   • 中型（10-50 个）：功能文件夹 + 共享组件
   • 大型（50+ 个）：完整的基于功能的架构

4. 展示具体示例：

   • 展示 assets/project-structure-example.md 中相关章节
   • 说明每个文件夹的用途

5. 提供迁移路径：

   • 不要一次性重构所有内容
   • 从新结构中的新功能开始
   • 逐步迁移旧代码

示例 4：“我需要创建许多相似的组件”

1. 使用组件生成器：

   # Generate multiple components at once
   python scripts/create_component.py UserCard --type component
   python scripts/create_component.py ProductCard --type component
   python scripts/create_component.py OrderCard --type component
   

2. 说明结构：

   • 展示生成的文件
   • 说明每个文件的用途
   • 根据需要进行自定义

3. 创建共享模式：

   • 将通用 props 提取到共享类型中
   • 创建基础 Card 组件
   • 使用组合模式

4. 参考模式指南：

   • 展示 references/best_practices.md 中的复合组件模式
   • 演示组件组合

示例 5：“帮我为 React 应用设置测试”

1. 参考测试设置：

   • 展示 assets/project-structure-example.md
   • 章节：“src/test/”文件夹结构

2. 设置测试工具：

   • 复制示例中的测试设置
   • 配置 vitest.config.ts
   • 创建测试工具（使用 providers 渲染）

3. 生成带测试的组件：

   # Components come with tests by default
   python scripts/create_component.py Button
   

4. 说明测试模式：

   • 参考 references/best_practices.md
   • 章节：“Testing Best Practices”
   • 展示组件和 hook 测试示例

5. 设置 CI/CD：

   • 添加 assets/package.json.example 中的测试脚本
   • 配置提交前钩子
   • 设置 GitHub Actions

使用此技能的最佳实践

全面作答

• 不要只回答问题，还要提供完整的解决方案
• 展示文件结构、配置和示例
• 解释推荐方案背后的“原因”

使用所有资源

• 脚本：生成代码以保持一致性
• 参考资料：深入了解概念
• 资源文件：可用于生产环境的配置和示例

遵循以下顺序

1. 了解：提出澄清问题
2. 参考：查阅相关文档
3. 生成：在适用时使用脚本
4. 说明：讲解模式/概念
5. 提供：给出完整可运行的示例

优先考虑性能

• 主动建议优化方案
• 定期运行 bundle analyzer
• 默认建议延迟加载
• 使用经过优化的配置

传授最佳实践

• 展示错误做法与正确做法
• 解释权衡取舍
• 参考 TypeScript 严格模式
• 鼓励测试

保持条理

• 尽早推荐基于功能的结构
• 从一开始就使用路径别名
• 确立命名约定
• 为扩展做好规划

参考文档

references/project_architecture.md

阅读时机：

• 组织新项目时
• 组织现有项目时
• 选择状态管理方案时
• 设置导入时
• 用户询问“我应该如何组织……？”时

主要章节：

• Optimal Folder Structure（2 种模式）
• Naming Conventions
• Component Organization Patterns
• State Management Strategies
• Import Strategies
• Decision Matrix

references/performance_optimization.md

阅读时机：

• 应用运行缓慢时
• 打包体积较大时
• 为生产环境进行优化时
• 用户询问性能相关问题时
• 部署前

主要章节：

• React 渲染优化（memo、useMemo、useCallback）
• 代码拆分
• 虚拟化
• Vite 构建优化
• 图片优化
• 网络性能
• CSS 性能
• Web Vitals 跟踪

references/best_practices.md

阅读时机：

• 实现模式
• TypeScript 问题
• 设置错误处理
• 表单实现
• 测试问题
• 代码审查

主要章节：

• 组件模式（5 种模式）
• TypeScript 最佳实践
• 错误处理模式
• 表单处理
• 测试最佳实践
• 常见反模式
• 无障碍访问

快速参考

常用命令

# Generate component
python scripts/create_component.py ComponentName --type component

# Generate page
python scripts/create_component.py PageName --type page

# Generate hook
python scripts/create_hook.py useHookName --type custom

# Analyze bundle
python scripts/analyze_bundle.py

常见问题

• “如何组织项目结构？” → references/project_architecture.md
• “如何优化性能？” → references/performance_optimization.md + 运行 analyze_bundle.py
• “应该使用哪种模式？” → references/best_practices.md
• “如何配置 Vite？” → assets/vite.config.optimized.ts
• “package.json 应该是什么样的？” → assets/package.json.example

文件结构优先级

1. 按功能组织（大型应用）——参见 references/project_architecture.md
2. 按组件组织（中型应用）——参见更简单的结构
3. 扁平结构（小型应用）——最少的组织结构

性能优化优先级

1. 代码拆分（优先拆分路由）
2. 移除大型依赖
3. 延迟加载（图像、组件）
4. 记忆化（开销较大的组件）
5. 虚拟化（长列表）

状态管理优先级

1. 服务端数据 → React Query
2. 本地状态 → useState
3. 简单的共享状态 → Context
4. 复杂的全局状态 → Zustand 或 Redux Toolkit

不适用此技能的情况

• 非 React 框架：Next.js 有自己的模式（使用 Next.js 技能）
• React Native：移动应用有不同的模式
• 类组件：重点是现代函数组件
• 非 Vite 构建工具：Webpack/Parcel 有不同的配置
• 后端开发：本指南侧重前端

对于这些主题，请提供通用的 React 指导，同时说明其局限性。

成功指标

你的 React + Vite 项目应达到以下指标：

• ✅ 初始压缩后的 Gzip 包体积 < 200KB
• ✅ Lighthouse 评分 > 90
• ✅ 所有测试均通过
• ✅ 无 ESLint 错误
• ✅ 文件结构一致
• ✅ 类型安全（TypeScript 严格模式）
• ✅ 构建速度快（生产构建 < 30s）
• ✅ HMR 速度快（< 100ms）