docs/v1.0/requirements/frontend/01-tech-stack.md

技术栈概览

文档版本：v1.1
最后更新：2025-01-18

---

目录

1. 核心技术栈
2. 开发工具
3. 特殊功能依赖
4. 技术选型理由
5. 依赖版本清单

---

1. 核心技术栈

1.1 基础框架

类别	技术选型	版本	说明
框架	React	^19.2.0	UI 框架
语言	TypeScript	~5.9.3	类型安全
构建工具	Vite	^7.2.4	快速构建、HMR

1.2 状态管理

类别	技术选型	版本	说明
客户端状态	Zustand	^5.0.5	轻量级状态管理
服务端状态	TanStack Query	^5.80.7	服务端状态管理

1.3 样式方案

类别	技术选型	版本	说明
CSS 框架	Tailwind CSS	^4.1.18	原子化 CSS (v4)
UI 组件库	shadcn/ui + Radix UI	latest	可定制组件
图标库	lucide-react	^0.562.0	图标集

1.4 网络与数据

类别	技术选型	版本	说明
HTTP 客户端	Axios	^1.10.0	API 请求
表单处理	React Hook Form	^7.57.0	表单验证
表单验证	Zod	^3.25.64	Schema 验证
日期处理	date-fns	^4.1.0	日期工具

1.5 路由与国际化

类别	技术选型	版本	说明
路由	React Router	^7.6.1	客户端路由
国际化	react-i18next	^15.5.2	多语言支持

1.6 交互功能

类别	技术选型	版本	说明
拖拽	@dnd-kit	^6.3.1 / ^10.0.0	拖拽排序

---

2. 开发工具

工具	用途
ESLint	代码质量检查 (Flat Config)
Prettier	代码格式化
Husky	Git Hooks
lint-staged	暂存文件检查

---

3. 特殊功能依赖

3.1 文档解析

依赖	版本	用途
fountain-js	^1.2.4	剧本格式解析
mammoth	^1.11.0	Word 文档解析
pdfjs-dist	^5.4.530	PDF 文件解析
turndown	^7.2.2	HTML 转 Markdown
react-markdown	^10.1.0	Markdown 渲染

---

4. 技术选型理由

4.1 React 19

选择理由：

• 并发渲染支持，提升大型列表和复杂交互的性能
• Suspense 支持异步数据加载
• 自动批处理减少渲染次数
• 成熟的生态系统

适用场景：

• 复杂的分镜列表渲染
• 时间轴的实时交互
• 大量组件的状态同步

4.2 Vite 7

选择理由：

• 基于 ESM 的极速开发服务器
• 快速的 HMR（热模块替换）
• 优化的生产构建
• 开箱即用的 TypeScript 支持
• 原生支持 Tailwind v4

性能优势：

• 开发服务器启动时间 < 1s
• HMR 更新时间 < 100ms
• 生产构建优化（Tree-shaking、代码分割）

4.3 Zustand 5

选择理由：

• 极简 API，学习成本低
• 无 Provider 包装，使用灵活
• TypeScript 原生支持
• 支持中间件扩展（devtools、persist）

对比其他方案：

• vs Redux：更轻量，无样板代码
• vs Context API：性能更好，避免不必要的重渲染
• vs Jotai/Recoil：更简单直观

4.4 Tailwind CSS v4 + shadcn/ui

选择理由：

• Tailwind v4 新特性：使用 @theme 指令配置，无需 JS 配置文件
• 原子化 CSS 减少样式冲突
• shadcn/ui 组件基于 Radix UI，可完全自定义
• 统一的设计系统（Pro Studio 主题）
• 优秀的开发体验

优势：

• 样式与组件解耦
• 响应式设计简单
• 深色模式支持完善
• 构建产物体积小

4.5 @dnd-kit

选择理由：

• 现代化的拖拽库
• 支持键盘无障碍访问
• 高性能，支持虚拟列表
• 用于分镜排序、时间轴编辑

适用场景：

• 分镜列表拖拽排序
• 时间轴轨道项拖拽
• 资源库拖拽上传

---

5. 依赖版本清单

5.1 生产依赖

{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "react-router-dom": "^7.6.1",
    "@tanstack/react-query": "^5.80.7",
    "@tanstack/react-query-devtools": "^5.80.7",
    "zustand": "^5.0.5",
    "axios": "^1.10.0",
    "zod": "^3.25.64",
    "react-hook-form": "^7.57.0",
    "@hookform/resolvers": "^5.1.0",
    "date-fns": "^4.1.0",
    "lucide-react": "^0.562.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.4.0",
    "class-variance-authority": "^0.7.1",
    "@radix-ui/react-*": "^1.0.0+",
    "@dnd-kit/core": "^6.3.1",
    "@dnd-kit/sortable": "^10.0.0",
    "@dnd-kit/utilities": "^3.2.2",
    "i18next": "^25.2.1",
    "react-i18next": "^15.5.2",
    "i18next-browser-languagedetector": "^8.0.5",
    "i18next-http-backend": "^3.0.2",
    "fountain-js": "^1.2.4",
    "mammoth": "^1.11.0",
    "pdfjs-dist": "^5.4.530",
    "turndown": "^7.2.2",
    "react-markdown": "^10.1.0",
    "remark-breaks": "^4.0.0"
  }
}

5.2 开发依赖

{
  "devDependencies": {
    "typescript": "~5.9.3",
    "vite": "^7.2.4",
    "@vitejs/plugin-react": "^5.1.1",
    "@tailwindcss/vite": "^4.1.18",
    "tailwindcss": "^4.1.18",
    "tailwindcss-animate": "^1.0.7",
    "@tailwindcss/typography": "^0.5.19",
    "postcss": "^8.5.6",
    "autoprefixer": "^10.4.23",
    "eslint": "^9.39.2",
    "@eslint/js": "^9.39.2",
    "typescript-eslint": "^8.52.0",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.4.26",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-prettier": "^5.5.4",
    "prettier": "^3.7.4",
    "globals": "^16.5.0",
    "husky": "^9.1.7",
    "lint-staged": "^16.2.7",
    "@types/node": "^24.10.1",
    "@types/react": "^19.2.5",
    "@types/react-dom": "^19.2.3",
    "@types/turndown": "^5.0.6"
  }
}

---

相关文档

• 项目结构
• 构建与开发环境
• 状态管理

---

最后更新：2025-01-18 | 版本：v1.1