项目结构指南
本文档说明 vitePress 项目的目录结构和文件组织。
根目录结构
vitePress/
├── src/ # 源代码目录
│ ├── components/ # React 组件库
│ │ ├── Button/
│ │ ├── Select/
│ │ ├── Form/
│ │ └── ...
│ ├── hooks/ # 自定义 React Hooks
│ │ ├── useGuide.ts # 交互导览
│ │ └── ...
│ ├── utils/ # 工具函数
│ │ └── ...
│ ├── types/ # TypeScript 类型定义
│ │ └── ...
│ └── ...
│
├── docs/ # VitePress 文档源
│ ├── knowledge/ # 知识库文章
│ │ ├── Event-Loop详解.md
│ │ ├── React-Diff算法详解.md
│ │ └── ...
│ ├── components/ # 组件文档
│ │ ├── Button/
│ │ └── ...
│ ├── guide/ # 用户指南
│ │ ├── api-examples.md
│ │ ├── cloud-capabilities.md
│ │ └── ...
│ ├── extra/ # 架构和优化文档
│ │ ├── ARCHITECTURE.md # 系统架构
│ │ ├── ROADMAP.md # 优化路线图
│ │ ├── COMPLETION-REPORT.md # 完成报告
│ │ ├── SECURITY.md # 安全指南
│ │ ├── DEVELOPMENT.md # 开发指南
│ │ └── ...
│ ├── index.md # 文档首页
│ └── ...
│
├── tests/ # 测试文件
│ ├── unit/ # 单元测试
│ │ ├── useGuide.test.ts
│ │ ├── setup.ts
│ │ └── ...
│ ├── e2e/ # 端到端测试
│ │ ├── basic.spec.ts
│ │ ├── advanced-interactions.spec.ts
│ │ └── ...
│ └── fixtures/ # 测试固定数据 (可选)
│
├── public/ # 静态资源
│ ├── debounce-throttle-demo.html
│ ├── event-loop-demo.html
│ ├── ...
│ ├── darkIcon/
│ ├── lightIcon/
│ └── ...
│
├── .github/ # GitHub 配置
│ ├── workflows/
│ │ └── ci.yml # CI/CD 流程
│ └── ...
│
├── .vitepress/ # VitePress 配置
│ ├── config.mts # 主配置文件
│ ├── theme/
│ │ ├── index.ts # 主题入口
│ │ ├── sentry-integration.ts # Sentry 监控
│ │ ├── performance-baseline.ts # 性能基准
│ │ ├── custom.css
│ │ └── ...
│ └── dist/ # 构建输出
│
├── 配置文件
├── .editorconfig
├── .eslintrc.json
├── eslint.config.js
├── .prettierrc.json
├── tsconfig.json
├── vitest.config.ts
├── playwright.config.ts
├── vite.config.ts
├── .gitignore
├── .prettierignore
├── .lintstagedrc.json
│
├── 文档文件（根目录）
├── README.md # 项目总览
├── CONTRIBUTING.md # 贡献指南
├── QUICK-REFERENCE.md # 快速参考
├── OPTIMIZATION-SUMMARY.md # 优化总结
├── LICENSE
│
└── package.json, pnpm-lock.yaml, .git ...文件分类说明
src/ - 源代码
存放项目的可复用源代码，包括：
- components/：React 组件库（Button, Select, Form 等）
- hooks/：自定义 React Hooks（useGuide 等）
- utils/：工具函数和帮助函数
- types/：TypeScript 类型定义
这些代码被用于：
- VitePress 主题组件中
- VitePress 组件演示中
- 作为可复用库供其他项目引用
docs/ - 文档源
VitePress 自动识别的文档源目录：
- knowledge/：知识库文章（Event Loop, React Diff 等）
- components/：组件使用文档
- guide/：用户指南和教程
- extra/：架构、优化、开发相关文档
- index.md：文档首页
所有 Markdown 文件在这里会被 VitePress 自动渲染为网页。
tests/ - 测试
项目测试文件分为两类：
- unit/：单元测试（*.test.ts）
- 测试组件、hooks、工具函数
- 使用 Vitest + React Testing Library
- e2e/：端到端测试（*.spec.ts）
- 测试用户完整的交互流程
- 使用 Playwright
public/ - 静态资源
不被 VitePress 处理的静态文件：
- HTML 交互演示页面
- 图片、图标
- 其他不需要编译的资源
.vitepress/ - VitePress 配置
VitePress 特定配置和主题：
- config.mts：VitePress 站点配置
- theme/：自定义主题和组件
- Vue 组件和样式
- 第三方集成（Sentry, Web Vitals 等）
导入路径规范
在 src/ 中的导入
typescript
// ✅ 相对导入
import { Button } from '../components/Button/button';
import { useGuide } from '../hooks/useGuide';
import { debounce } from '../utils/debounce';
// ✅ 别名导入（tsconfig.json 中配置）
import { Button } from '@/components/Button/button';
import { useGuide } from '@/hooks/useGuide';在 .vitepress/theme/ 中的导入
typescript
// ✅ 相对导入 src
import { Button } from '../../src/components/Button/button';
// ✅ 使用别名
import { Button } from '@/components/Button/button';在文档（Markdown）中
markdown
<!-- VitePress 自动处理相对路径 -->
[查看 Button 组件](../components/Button)
[知识库](../knowledge/)
<!-- 也可以使用别名（如果在 VitePress 中配置） -->
[查看组件文档](/front/components/)构建和开发命令
bash
# 文档开发
pnpm docs:dev # 启动 VitePress 开发服务（http://localhost:5173）
# 组件开发
pnpm dev # 启动 VitePress（组件文档与知识站统一在 5173）
# 测试
pnpm test # 运行单元测试
pnpm test:e2e # 运行 E2E 测试
pnpm test:coverage # 生成测试覆盖率报告
# 构建
pnpm build # 生产构建
pnpm build:analyze # Bundle 分析报告
# 代码质量
pnpm lint # 检查代码
pnpm lint:fix # 自动修复代码
pnpm format # 格式化代码
pnpm typecheck # TypeScript 类型检查关键文件说明
package.json
定义项目的依赖和脚本。主要脚本包括：
docs:dev/docs:build：VitePress 命令dev：VitePress 开发命令test/test:e2e：测试命令lint、format、typecheck：代码质量工具
tsconfig.json
TypeScript 配置，包括：
- 路径别名（
@/指向 src） - 编译选项
- 类型库引用
vitest.config.ts
单元测试配置：
- 测试环境
- 覆盖率阈值
- 文件 glob 模式
playwright.config.ts
E2E 测试配置：
- 浏览器配置
- 超时设置
- 报告输出
.vitepress/config.mts
VitePress 核心配置：
- 站点元数据
- 导航和侧边栏
- Markdown 插件
- 构建优化
添加新文件的位置
添加新组件
src/components/YourComponent/
├── component.tsx # 组件源码
├── component.test.tsx # 单元测试
├── index.md # VitePress 组件文档
└── index.ts # 导出添加新 Hook
src/hooks/
├── useYourHook.ts # Hook 源码
└── useYourHook.test.ts # 测试添加新知识文章
docs/knowledge/
└── 你的主题.md # Markdown 文章添加新文档页面
根据类型放入对应目录：
docs/guide/ # 用户指南
docs/extra/ # 架构/优化/开发文档
docs/api/ # API 参考（新增）文件搜索快速引用
组件源码
src/components/ComponentName/component.tsx组件样式
src/components/ComponentName/component.css组件测试
tests/unit/ComponentName.test.tsx组件文档
docs/components/ComponentName/index.md知识文章
docs/knowledge/文章名.md主题配置
.vitepress/theme/index.ts网站配置
.vitepress/config.mts最佳实践
不要在根目录放置源代码文件
- ✅ 代码应该在
src/或tests/中 - ❌ 避免在根目录放
.ts,.tsx,.jsx文件
- ✅ 代码应该在
文件组织要按功能
- ✅
src/components/Button/包含所有 Button 相关文件 - ❌ 不要把 Button 分散到不同目录
- ✅
测试文件紧跟源代码
- ✅
src/hooks/useGuide.ts+tests/unit/useGuide.test.ts - ❌ 不要把测试和源代码分离太远
- ✅
文档路径反映层级
- ✅
docs/components/Button/index.md对应src/components/Button/ - ❌ 避免不一致的路径命名
- ✅
使用路径别名
- ✅
import { Button } from '@/components/Button' - ❌ 避免
../../../这样的相对路径
- ✅
最后更新：2026-03-06 维护者：cmwrun 团队