开发指南
详细的开发和构建说明。
快速开始
bash
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 构建生产版本
pnpm build
# 本地预览
pnpm preview
# 运行测试
pnpm test项目结构
vitePress/
├── front/ # 前端内容和组件
│ ├── components/ # React 可交互组件
│ │ ├── Button/ # 按钮组件
│ │ ├── Form/ # 表单相关
│ │ └── Select/ # 选择器组件
│ └── knowledge/ # 知识库文章（Markdown）
├── public/ # 静态资源和演示页面
│ ├── *.html # 交互式演示页面
│ └── ...
├── tests/ # Playwright E2E 测试
├── .vitepress/ # VitePress 配置
│ ├── config.mts # 主配置文件
│ └── theme/ # 主题定制
├── .github/workflows/ # CI/CD 工作流
├── package.json # 项目依赖和脚本
├── tsconfig.json # TypeScript 配置
├── eslint.config.js # ESLint 配置
└── .prettierrc.json # Prettier 配置脚本命令
开发
| 命令 | 说明 |
|---|---|
pnpm dev | 启动开发服务器 (http://localhost:5173) |
pnpm build | 构建生产版本 |
pnpm preview | 本地预览构建结果 |
质量保证
| 命令 | 说明 |
|---|---|
pnpm typecheck | TypeScript 类型检查 |
pnpm lint | ESLint 代码检查 |
pnpm lint:fix | 自动修复 ESLint 问题 |
pnpm format | Prettier 代码格式化 |
测试
| 命令 | 说明 |
|---|---|
pnpm test | 运行 Playwright 测试 |
pnpm test:ui | UI 模式运行测试 |
pnpm test:headed | 显示浏览器运行测试 |
pnpm link:check | 检查链接有效性 |
技术栈
- VitePress: 1.6.4 - 文档网站生成器
- React: 19.2.3 - UI 框架
- TypeScript: 5.9.3 - 类型检查
- Playwright: ^1.58.2 - E2E 测试框架
- Three.js: ^0.182.0 - 3D 图形库
- MobX: ^6.13.7 - 状态管理
工具配置
ESLint
代码规范检查，配置文件：eslint.config.js
bash
pnpm lint # 检查所有文件
pnpm lint:fix # 自动修复问题Prettier
代码格式化，配置文件：.prettierrc.json
bash
pnpm format # 格式化所有文件Husky + lint-staged
Pre-commit 钩子，自动在提交前检查和格式化代码。
配置文件：
.husky/pre-commit- Pre-commit 钩子.lintstagedrc.json- 分阶段检查配置
常见任务
添加新知识文章
- 在
front/knowledge/中创建.md文件 - 修改
.vitepress/config.mts的sidebar配置 - 运行
pnpm dev预览
创建新组件
- 在
front/components/创建组件目录 - 编写
.tsx文件（使用 TypeScript） - 创建
index.md文档 - 在配置中添加导航
TypeScript 规范：
- 必须完整的类型注解
- 禁用
any类型 - 使用命名导出
typescript
// ✅ 正确
export interface ButtonProps {
label: string;
onClick: () => void;
}
export { Button };
// ❌ 错误
export default Button;
button.tsx: export default Button创建交互演示
- 在
public/创建.html文件 - 使用 Vanilla JS 或 React
- 在文章中用
iframe或demo标签嵌入
修改网站样式
VitePress 主题文件在 .vitepress/theme/，可自定义 CSS 变量和组件外观。
构建和部署
本地构建
bash
pnpm build # 生成静态文件到 dist/
pnpm preview # 本地预览构建结果自动部署
Push 到 master 分支后，GitHub Actions 自动：
- 运行类型检查和代码检查
- 运行 E2E 测试
- 构建生产版本
- 部署到托管平台
调试技巧
调试 VitePress
bash
# 开发服务器支持热部署
pnpm dev
# 修改文件后浏览器自动刷新调试测试
bash
# UI 模式查看测试过程
pnpm test:ui
# 显示浏览器运行（便于观察）
pnpm test:headed
# 单个测试文件
pnpm test tests/basic.spec.ts浏览器控制台
在演示页面中点击浏览器的开发者工具（F12），查看控制台消息。
性能优化
- 图片使用 WebP 格式
- 使用代码分割和动态导入
- 启用 Gzip 压缩
- 使用 CDN 加速
常见问题
依赖版本冲突
bash
# 清新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install端口被占用
bash
# 使用其他端口
pnpm dev --port 5174类型检查失败
bash
# 重新生成类型
pnpm typecheck