🚀 项目命令快速参考
IMPORTANT
历史归档说明（2026-03-11）：本文中出现的 Storybook 命令与目录路径为历史记录。当前项目已统一迁移为 VitePress 组件文档方案，请优先使用 pnpm dev 和组件目录下的 index.md 文档。
开发相关
启动本地开发
bash
pnpm dev # 启动 VitePress 开发服务器 (5173 端口)
pnpm preview # 预览生产构建组件开发和文档
bash
pnpm dev # 启动组件文档（VitePress）
pnpm build # 构建组件文档站点- 组件文档入口：
front/components/*/index.md - 交互示例推荐：
<demo react="./xxx.demo.tsx"/>
测试相关
单元测试
bash
pnpm test # 运行所有单元测试
pnpm test:ui # 启动 Vitest UI 界面
pnpm test:watch # 监视模式（代码改动自动重新运行）
pnpm test:coverage # 生成覆盖率报告（lcov.info）E2E 测试（Playwright）
bash
pnpm test:e2e # 运行所有 E2E 测试（无界面）
pnpm test:e2e:ui # E2E 测试交互式 UI
pnpm test:e2e:headed # 显示浏览器窗口运行 E2E 测试覆盖率查看
bash
# 生成覆盖率报告后
open coverage/index.html代码质量检查
类型检查和 Lint
bash
pnpm typecheck # TypeScript 类型检查
pnpm lint # ESLint 代码检查
pnpm lint:fix # 自动修复 ESLint 问题
pnpm format # Prettier 代码格式化完整的代码质量检查
bash
pnpm lint:fix && pnpm format && pnpm typecheck构建和分析
生产构建
bash
pnpm build # 构建 VitePress 站点
pnpm build:analyze # 生成 Bundle 分析报告
# 报告位置：.vitepress/dist/bundle-analysis.html
# 在浏览器中打开查看交互式 bundle 分析查看分析报告
bash
open .vitepress/dist/bundle-analysis.html性能相关
链接检查
bash
pnpm link:check # 检查所有链接（仅针对线上网站）审计相关
安全审计
bash
pnpm audit # 检查依赖的安全漏洞工作流速查表
🔄 常规开发流程
bash
# 1. 创建功能分支
git checkout -b feat/my-feature
# 2. 启动开发服务器
pnpm dev
# 3. 必要时启动 Storybook
pnpm storybook
# 4. 编写代码和测试
# 创建/修改组件和测试文件
# 5. 运行测试（监视模式）
pnpm test:watch
# 6. 代码质量检查
pnpm lint:fix
pnpm format
pnpm typecheck
# 7. 提交代码
git add .
git commit -m "feat(components): 描述变更"✅ 提交前检查清单
bash
# 1. 单元测试
pnpm test
# 2. E2E 测试（可选）
pnpm test:e2e
# 3. 代码质量
pnpm lint
pnpm format
pnpm typecheck
# 4. TypeScript 检查
pnpm typecheck
# 5. 构建验证
pnpm build🚀 发布前完整检查
bash
# 1. 完整测试
pnpm test:coverage
pnpm test:e2e
# 2. 代码质量
pnpm lint
pnpm format
pnpm typecheck
# 3. 构建和分析
pnpm build
pnpm build:analyze
# 4. 审计
pnpm audit
# 5. 链接检查（仅限 staging）
# pnpm link:check📁 重要文件位置
配置文件
.storybook/
├── main.ts # Storybook 主配置
└── preview.ts # Storybook 预览配置
vitest.config.ts # 单元测试配置
playwright.config.ts # E2E 测试配置
tsconfig.json # TypeScript 配置
eslint.config.js # ESLint 配置
prettier.config.js # Prettier 配置
.github/workflows/
└── ci.yml # GitHub Actions 工作流测试文件
tests/
├── basic.spec.ts # 基础功能测试
├── advanced-interactions.spec.ts
├── navigation.spec.ts
├── user-flows.spec.ts
├── interactions.spec.ts
└── comprehensive.spec.ts # 综合测试套件
front/components/
├── Button/button.test.tsx
├── Select/select.test.tsx
└── Button/button.stories.tsx
Select/select.stories.tsx性能监控文件
.vitepress/theme/
├── performance.ts # Web Vitals 监控
├── error-tracking.ts # 错误追踪
├── performance-baseline.ts # 性能基准线
├── sentry-integration.ts # Sentry 集成
└── index.ts # 主题入口（初始化监控）🔗 环境变量（可选）
.env.local（本地开发）
bash
# Sentry 错误追踪（可选）
VITE_SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
# 性能分析端点（可选）
VITE_ANALYTICS_ENDPOINT=https://your-analytics.com/api/vitals📊 输出位置
测试报告
coverage/ # 单元测试覆盖率
├── lcov.info
└── index.html # 可视化覆盖率报告
test-results/ # E2E 测试结果
junit.xml # JUnit 格式测试报告
playwright-report/
└── index.html # Playwright 测试报告构建输出
.vitepress/dist/ # 生产构建输出
├── bundle-analysis.html # Bundle 大小分析
└── [其他网站文件]
storybook-static/ # Storybook 静态构建🐛 常见问题排查
测试失败
bash
# 1. 检查依赖是否安装完整
pnpm install
# 2. 清除缓存
rm -rf node_modules/.vite
pnpm store prune
# 3. 重新运行测试
pnpm test -- --runESLint 错误
bash
# 自动修复大多数问题
pnpm lint:fix
# 查看详细错误
pnpm lint代码格式问题
bash
# 使用 Prettier 格式化
pnpm format类型检查错误
bash
# 运行类型检查查看详细信息
pnpm typecheck构建失败
bash
# 1. 清除构建缓存
rm -rf .vitepress/dist
# 2. 重新构建
pnpm build💡 最佳实践
开发期间
- ✅ 使用
pnpm test:watch进行实时测试 - ✅ 使用
pnpm storybook查看组件 - ✅ 使用 VS Code ESLint 扩展进行实时检查
- ❌ 避免犯罪 console.log 和 debugger
提交前
- ✅ 运行
pnpm lint:fix && pnpm format - ✅ 确保所有测试通过
- ✅ 遵循约定式提交格式
- ❌ 不要跳过 pre-commit hook
大功能开发
- ✅ 创建功能分支（feat/xxx）
- ✅ 为新功能编写测试
- ✅ 在 Storybook 中创建故事
- ✅ 更新文档和 CONTRIBUTING.md
📚 文档链接
- CONTRIBUTING.md - 完整贡献指南
- OPTIMIZATION-SUMMARY.md - 优化总结报告
- README.md - 项目概览
最后更新: 2026-03-06 保持更新: 定期检查新的工具和工作流