贡献指南

IMPORTANT

历史归档说明（2026-03-11）：本文件中若出现 Storybook 示例或命令，均为历史内容。当前项目组件文档已统一为 VitePress 方案，请以 front/components/**/index.md 与 <demo react="..."/> 为准。

感谢你有兴趣贡献到 VitePress 项目！本指南会帮助你了解如何参与项目开发。

开发环境设置

前提条件

Node.js >= 18
pnpm >= 9.15.2

安装步骤

bash

# 1. 克隆仓库
git clone https://github.com/cmw-big/vitePress.git
cd vitePress

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev

# 4. 访问本地网站
# 浏览器打开 http://localhost:5173

开发工作流

1. 创建新分支

bash

# 从 master 创建新分支
git checkout -b feature/my-feature
# 或
git checkout -b fix/my-bug

2. 编码规范

本项目遵循以下规范：

TypeScript

✅ 必须使用完整的类型注解
✅ 启用 strict: true 模式
❌ 禁止使用 any 类型
❌ 禁止使用拼音命名

React 组件

✅ 使用函数式组件 + Hooks
✅ 使用命名导出 (export { Component })
✅ 为所有 Props 定义接口
❌ 禁止使用 default export

代码质量

❌ 禁止 console.log 和 debugger 语句
✅ 使用 ESLint 检查代码 (pnpm lint)
✅ 使用 Prettier 格式化代码 (pnpm format)

3. 运行检查

bash

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# 自动修复 eslint 问题
pnpm lint:fix

# 代码格式化
pnpm format

# 运行单元测试
pnpm test

# 运行测试并生成覆盖率报告
pnpm test:coverage

# 启动测试 UI 界面
pnpm test:ui

# 监视模式运行测试（开发时实时更新）
pnpm test:watch

# 运行 E2E 测试（Playwright）
pnpm test:e2e

# 运行 E2E 测试工具界面
pnpm test:e2e:ui

# 生成 Bundle 分析报告（可视化包大小）
pnpm build:analyze

4. 提交代码

项目启用了 pre-commit 钩子，确保：

ESLint 检查通过
代码格式符合标准
没有 console.log/debugger

bash

# 暂存文件
git add .

# 提交（会自动运行钩子）
git commit -m "feat: 添加新功能"

# 如果需要跳过钩子（不推荐）
git commit --no-verify -m "..."

提交信息规范

使用 Angular 风格的提交信息：

<type>(<scope>): <subject>

<body>

<footer>

Type 类型

feat: 新功能
fix: bug 修复
docs: 文档更新
style: 代码样式（空格、格式等）
refactor: 重构代码
perf: 性能优化
test: 测试相关
chore: 构建工具、依赖更新等

示例

feat(components): 新增 Select 组件

- 支持键盘导航
- 支持搜索过滤
- 支持异步加载

Closes #123

单元测试规范

为什么需要测试？

提高code质量和可靠性
防止回归bug
作为文档更新组件使用方式
提高重构信心

测试框架

本项目使用：

Vitest：快速的单元测试框架
React Testing Library：React 组件测试库
@testing-library/user-event：模拟用户交互

编写测试

typescript

import { describe, it, expect, beforeEach } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

describe('Button', () => {
  it('should render button text', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('should call onClick when clicked', async () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click</Button>);

    await userEvent.click(screen.getByText('Click'));
    expect(handleClick).toHaveBeenCalled();
  });

  it('should be disabled when prop is set', () => {
    render(<Button disabled>Disabled</Button>);
    expect(screen.getByText('Disabled')).toBeDisabled();
  });
});

测试覆盖率要求

最低要求：60% 整体覆盖率
目标：75% 以上覆盖率
关键路径：100% 覆盖（核心业务逻辑）

最佳实践

优先测试用户行为，而不是实现细节
使用语义选择器：getByRole() > getByLabelText() > getByText()
避免过度具体化：不要测试样式细节
隔离依赖：使用 vi.mock() 模拟外部依赖
使用 beforeEach：共享测试设置

性能监控与错误追踪

本项目已集成以下性能监控工具：

Web Vitals 监控

关键性能指标自动监控：

CLS (Cumulative Layout Shift)：累积布局偏移
FID (First Input Delay)：首次输入延迟
FCP (First Contentful Paint)：首次内容绘制
LCP (Largest Contentful Paint)：最大内容绘制
TTFB (Time to First Byte)：首字节时间

Development 环境会输出日志，生产环境可配置上报端点。

错误追踪

自动捕获：

全局 JavaScript 错误
Promise 拒绝异常
资源加载失败（图片、脚本等）
代码分割加载失败

配置端点即可自动上报错误。

性能优化建议

Bundle 分析

bash

# 生成可视化的 bundle 分析报告
pnpm build:analyze
# 报告输出在 .vitepress/dist/bundle-analysis.html

通过分析报告：

识别过大的依赖
优化代码分割
减少首屏加载时间

常见优化

✅ 使用动态导入：() => import('./lazy')
✅ 启用 Route-based code splitting
✅ 优化图片：使用 WebP、压缩
✅ 启用 gzip/brotli 压缩
❌ 避免导入整个库，使用按需导入

提交 Pull Request

更新分支：确保与主分支同步

bash

git fetch origin
git rebase origin/master

推送分支
bash
```
git push origin feature/my-feature
```
1
创建 PR：在 GitHub 上提交 PR，填写完整的描述
等待审查：维护者会审查你的代码

E2E 测试规范

使用 Playwright

端到端测试框架使用 Playwright，测试文件位于 tests/ 目录。

编写 E2E 测试

typescript

import { test, expect } from '@playwright/test';

test('navigate to knowledge page', async ({ page }) => {
  // 访问首页
  await page.goto('/');

  // 点击导航链接
  await page.click('a[href="/front/knowledge"]');

  // 验证 URL
  await expect(page).toHaveURL('/front/knowledge');

  // 验证页面内容
  await expect(page.locator('h1')).toContainText('知识和矩阵');
});

test('search functionality', async ({ page }) => {
  await page.goto('/');

  // 输入搜索词
  await page.fill('input[placeholder="Search"]', 'React');
  await page.press('input', 'Enter');

  // 等待搜索结果加载
  await page.waitForLoadState('networkidle');

  // 验证结果数量 > 0
  const results = await page.locator('[data-test="search-result"]').count();
  expect(results).toBeGreaterThan(0);
});

E2E 最佳实践

使用 data-testid：为可测试元素添加属性
html
```
<button data-testid="submit-btn">Submit</button>
```
1

等待合适的加载状态：

typescript

await page.waitForLoadState('networkidle'); // 网络空闲
await page.waitForSelector('.item'); // 元素出现

避免 sleep：使用显式等待而不是 page.waitForTimeout()
测试用户流程：完整的业务流程而不是单个动作

代码审查流程

PR 需要通过：

✅ GitHub Actions（CI 检查）
✅ 代码审查（至少 1 个维护者）

报告 Bug

如果发现 bug，请创建 Issue 并包含：

清晰的标题和描述
复现步骤
期望行为
实际行为
环境信息（浏览器、系统等）

编码教程

添加新页面

在 front/knowledge/ 或相应目录创建 .md 文件
在 .vitepress/config.mts 的 sidebar 中添加导航
使用 front matter 配置元数据

添加新组件

在 front/components/ 创建组件目录
编写 TypeScript React 组件
创建 index.md 文档
在 .vitepress/config.mts 中添加导航

创建交互演示

在 public/ 创建 .html 文件
使用 Vanilla JS 或内联 React
在知识文章中通过 <iframe> 引用

有问题？

检查 README.md
查看 FEATURES.md 了解项目特性
提交 Issue 反馈问题

组件文档与演示

本项目统一使用 VitePress 管理组件文档与交互演示。

启动组件文档

bash

pnpm dev
# 默认访问 http://localhost:5173

编写组件文档

在 front/components/<ComponentName>/ 下维护组件源码。
使用 index.md 作为组件文档入口。
使用 *.demo.tsx 承载交互示例，并在文档中通过 <demo react="./xxx.demo.tsx"/> 引用。

文档最佳实践

✅ 覆盖核心 props、边界状态和错误恢复路径
✅ 示例代码与真实组件 API 保持一致
✅ 提供可运行 demo，而不是仅静态代码片段
✅ 修改组件后同步更新 index.md 中的 API 表格与示例

性能监控贡献

Web Vitals 监控

如需监控新的性能指标，编辑 .vitepress/theme/performance.ts:

typescript

import { onCLS, onFID, onFCP, onLCP, onTTFB } from 'web-vitals';

function setupWebVitals() {
  // 添加你的监控逻辑
  onCLS((metric) => {
    console.log('CLS:', metric.value);
    // 可选：上报到分析服务
  });
}

性能基准线

更新性能基准线阈值，编辑 .vitepress/theme/performance-baseline.ts:

typescript

const BENCHMARKS = {
  FCP: { baseline: 1000, warning: 1800, critical: 3000 },
  LCP: { baseline: 2500, warning: 4000, critical: 4500 },
  // 添加更多指标...
};

错误追踪

为更好的错误监控，编辑 .vitepress/theme/sentry-integration.ts:

typescript

// 添加自定义错误分类
export function captureCustomEvent(category: string, message: string) {
  // 实现自定义事件追踪
}

CI/CD 工作流

了解当前工作流

项目使用 GitHub Actions 自动化，配置在 .github/workflows/ci.yml。

7 个并行/依赖任务：

check (TypeScript, ESLint, Prettier) ──┐
unit-test (Vitest) ──────────────────┬─┤
build (VitePress) ────────┬──────────┤ ├─→ all-checks
                          ├──→ e2e-test
                          └──→ performance-analysis
security-audit (npm audit) ──────────┘

执行时间：~12-15 分钟（并行优化）

改进 CI/CD

为工作流添加新的检查步骤，编辑 .github/workflows/ci.yml:

yaml

- name: Custom Check
  run: pnpm custom:check
  # 或添加为新的 job

贡献技术栈说明

前端框架

VitePress 1.6.4：文档站点生成器
Vue 3：主题和布局组件
React 19：可复用组件库
TypeScript 5：类型安全开发

测试框架

Vitest：高性能单元测试
React Testing Library：组件测试
Playwright：E2E 端到端测试

开发工具

Vite 7：前端构建工具
ESLint：代码检查
Prettier：代码格式化
Storybook 10：组件库文档

监控和分析

Web Vitals：性能指标标准库
Sentry：错误追踪平台（可选）
Bundle Analyzer：包体积分析

许可证

本项目采用 MIT 许可证。贡献代码即表示你同意将代码贡献到本项目。

贡献指南 ​

开发环境设置 ​

前提条件 ​

安装步骤 ​

开发工作流 ​

1. 创建新分支 ​

2. 编码规范 ​

TypeScript ​

React 组件 ​

代码质量 ​

3. 运行检查 ​

4. 提交代码 ​

提交信息规范 ​

Type 类型 ​

示例 ​

单元测试规范 ​

为什么需要测试？ ​

测试框架 ​

编写测试 ​

测试覆盖率要求 ​

最佳实践 ​

性能监控与错误追踪 ​

Web Vitals 监控 ​

错误追踪 ​

性能优化建议 ​

Bundle 分析 ​

常见优化 ​

提交 Pull Request ​

E2E 测试规范 ​

使用 Playwright ​

编写 E2E 测试 ​

E2E 最佳实践 ​

代码审查流程 ​

报告 Bug ​

编码教程 ​

添加新页面 ​

添加新组件 ​

创建交互演示 ​

有问题？ ​

组件文档与演示 ​

启动组件文档 ​

编写组件文档 ​

文档最佳实践 ​

性能监控贡献 ​

Web Vitals 监控 ​

性能基准线 ​

错误追踪 ​

CI/CD 工作流 ​

了解当前工作流 ​

改进 CI/CD ​

贡献技术栈说明 ​

前端框架 ​

测试框架 ​

开发工具 ​

监控和分析 ​

许可证 ​

贡献指南

开发环境设置

前提条件

安装步骤

开发工作流

1. 创建新分支

2. 编码规范

TypeScript

React 组件

代码质量

3. 运行检查

4. 提交代码

提交信息规范

Type 类型

示例

单元测试规范

为什么需要测试？

测试框架

编写测试

测试覆盖率要求

最佳实践

性能监控与错误追踪

Web Vitals 监控

错误追踪

性能优化建议

Bundle 分析

常见优化

提交 Pull Request

E2E 测试规范

使用 Playwright

编写 E2E 测试

E2E 最佳实践

代码审查流程

报告 Bug

编码教程

添加新页面

添加新组件

创建交互演示

有问题？

组件文档与演示

启动组件文档

编写组件文档

文档最佳实践

性能监控贡献

Web Vitals 监控

性能基准线

错误追踪

CI/CD 工作流

了解当前工作流

改进 CI/CD

贡献技术栈说明

前端框架

测试框架

开发工具

监控和分析

许可证