# nextjs-demo

**Repository Path**: realyyycz/nextjs-demo

## Basic Information

- **Project Name**: nextjs-demo
- **Description**: 一个基于Next.js的示例项目，展示如何构建现代Web应用，包括路由、状态管理等，适合初学者和开发者学习参考。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: nextjs, React, TypeScript, Nodejs, JavaScript

## README

# Next.js Demo 项目

这是一个基于 Next.js 15 的现代化 Web 应用演示项目，集成了最新的前端开发工具链和最佳实践。

- [Next.js Demo 项目](#nextjs-demo-项目)
  - [🚀 技术栈](#-技术栈)
    - [核心框架](#核心框架)
    - [开发工具](#开发工具)
    - [样式与构建](#样式与构建)
    - [测试工具](#测试工具)
  - [📦 快速开始](#-快速开始)
    - [环境要求](#环境要求)
    - [安装依赖](#安装依赖)
    - [启动开发服务器](#启动开发服务器)
  - [📁 项目结构](#-项目结构)
    - [代码组织规范](#代码组织规范)
  - [🎨 代码规范](#-代码规范)
    - [代码格式化](#代码格式化)
    - [编辑器配置](#编辑器配置)
    - [ESLint 规则](#eslint-规则)
  - [📝 Git 提交规范](#-git-提交规范)
    - [Gitmoji 提交规范](#gitmoji-提交规范)
    - [常用 Gitmoji](#常用-gitmoji)
    - [提交前检查](#提交前检查)
  - [🧪 Cypress 测试指南](#-cypress-测试指南)
    - [测试环境设置](#测试环境设置)
    - [编写测试示例](#编写测试示例)
    - [最佳实践](#最佳实践)
    - [持续集成](#持续集成)
  - [👥 团队协作](#-团队协作)
    - [分支策略](#分支策略)
    - [开发流程](#开发流程)
    - [代码审查要点](#代码审查要点)
  - [❓ 常见问题](#-常见问题)
    - [Q: 如何添加新的页面？](#q-如何添加新的页面)
    - [Q: 如何添加新的组件？](#q-如何添加新的组件)
    - [Q: 提交时遇到格式错误怎么办？](#q-提交时遇到格式错误怎么办)
    - [Q: 如何添加新的依赖？](#q-如何添加新的依赖)
    - [Q: 如何运行测试？](#q-如何运行测试)
    - [Q: 如何调试测试失败？](#q-如何调试测试失败)
  - [🛠️ 开发脚本](#️-开发脚本)
  - [📄 许可证](#-许可证)
  - [🤝 贡献](#-贡献)

## 🚀 技术栈

### 核心框架

- **Next.js 15** - 全栈 React 框架，支持 App Router
- **React 19** - 最新版本的 React
- **TypeScript** - 类型安全的 JavaScript

### 开发工具

- **ESLint** - 代码质量检查
- **Prettier** - 代码格式化
- **Husky** - Git 钩子管理
- **lint-staged** - 提交前代码检查

### 样式与构建

- **Tailwind CSS v4** - 实用优先的 CSS 框架
- **Turbopack** - 快速的构建工具

### 测试工具

- **Cypress** - E2E 测试框架

> 📚 **参考文档**: [Next.js 官方文档](https://nextjs.org/docs) | [React 官方文档](https://react.dev) | [TypeScript 官方文档](https://www.typescriptlang.org) | [Tailwind CSS 文档](https://tailwindcss.com/docs)

## 📦 快速开始

### 环境要求

- Node.js 18+
- pnpm 8+

### 安装依赖

```bash
pnpm install
```

### 启动开发服务器

```bash
# 开发模式 (使用 Turbopack 加速)
pnpm dev

# 构建生产版本
pnpm build

# 启动生产服务器
pnpm start
```

访问 [http://localhost:3000](http://localhost:3000) 查看应用。

> 📚 **参考文档**: [Next.js 快速开始](https://nextjs.org/docs/getting-started) | [pnpm 安装指南](https://pnpm.io/installation)

## 📁 项目结构

```text
nextjs-demo/
├── app/                 # App Router 目录
│   ├── layout.tsx       # 根布局组件
│   └── page.tsx         # 首页组件
├── components/          # 可复用组件目录
├── lib/                 # 工具函数和配置
├── hooks/               # 自定义 React Hooks
├── types/               # TypeScript 类型定义
├── styles/              # 全局样式文件
├── public/              # 静态资源
├── cypress/             # Cypress 测试文件
│   ├── e2e/             # E2E 测试文件
│   ├── fixtures/        # 测试数据
│   └── support/         # 测试支持文件
├── .husky/              # Git 钩子配置
├── eslint.config.js     # ESLint 配置
├── next.config.ts       # Next.js 配置
├── tsconfig.json        # TypeScript 配置
└── package.json         # 项目依赖和脚本
```

### 代码组织规范

- **页面组件**: 放在 `app/` 目录下，使用 Next.js App Router
- **通用组件**: 放在 `components/` 目录，按功能模块组织
- **业务逻辑**: 放在 `lib/` 目录，包含 API 调用、数据处理等
- **自定义 Hooks**: 放在 `hooks/` 目录
- **类型定义**: 放在 `types/` 目录
- **工具函数**: 放在 `utils/` 目录
- **E2E 测试**: 放在 `cypress/e2e/` 目录
- **测试数据**: 放在 `cypress/fixtures/` 目录
- **测试支持**: 放在 `cypress/support/` 目录

> 📚 **参考文档**: [Next.js App Router](https://nextjs.org/docs/app) | [React 组件最佳实践](https://react.dev/learn/your-first-component)

## 🎨 代码规范

### 代码格式化

项目使用 Prettier 进行自动格式化：

```bash
# 格式化所有文件
pnpm format

# 检查代码风格
pnpm lint

# 检查代码风格并修复可以自动修复的问题
pnpm lint:fix
```

### 编辑器配置

项目包含 `.editorconfig` 文件，确保团队代码风格一致：

- 使用空格缩进，2个空格
- UTF-8 编码
- LF 换行符
- 自动删除行尾空格

### ESLint 规则

项目配置了严格的 ESLint 规则，包括：

- **Import 排序**: 自动排序导入语句
- **Promise 处理**: 强制正确的 Promise 使用
- **安全规则**: 检测潜在的安全问题
- **React Hooks**: 强制 Hooks 规则

> 📚 **参考文档**: [Prettier 配置](https://prettier.io/docs/en/configuration.html) | [ESLint 规则](https://eslint.org/docs/rules/) | [EditorConfig](https://editorconfig.org/)

## 📝 Git 提交规范

### Gitmoji 提交规范

项目使用 Gitmoji 规范，所有提交必须包含 emoji：

```bash
# 正确格式
✨ 添加用户登录功能
🐛 修复登录页面样式问题
📝 更新 API 文档

# 错误格式
添加用户登录功能  # 缺少 emoji
```

### 常用 Gitmoji

- ✨ `:sparkles:` - 引入新功能
- 🐛 `:bug:` - 修复 bug
- 📝 `:memo:` - 编写文档
- ♻️ `:recycle:` - 重构代码
- 🔧 `:wrench:` - 修改配置文件
- 💄 `:lipstick:` - 更新 UI 和样式
- 🚀 `:rocket:` - 部署相关
- ✅ `:white_check_mark:` - 添加测试

### 提交前检查

项目配置了 Husky 钩子，在提交前会自动：

1. 运行 ESLint 检查
2. 运行 Prettier 格式化
3. 验证提交信息格式

> 📚 **参考文档**: [Gitmoji 规范](https://gitmoji.dev/) | [Husky 配置](https://typicode.github.io/husky/)

## 🧪 Cypress 测试指南

### 测试环境设置

项目已配置 Cypress 作为 E2E 测试框架。要开始使用测试：

```bash
# 首次运行需要初始化 Cypress
pnpm test:install

# 打开 Cypress 测试界面
pnpm test:open

# 运行所有测试 (headless 模式)
pnpm test

# 仅运行组件测试
pnpm test:component

# 仅运行 E2E 测试
pnpm test:e2e
```

### 编写测试示例

```typescript
// cypress/e2e/home.cy.ts
describe('首页测试', () => {
  beforeEach(() => {
    cy.visit('/')
  })

  it('应该正确显示页面标题', () => {
    cy.get('h1').should('contain', '欢迎使用 Next.js')
  })

  it('应该能够导航到其他页面', () => {
    cy.get('nav a').first().click()
    cy.url().should('include', '/about')
  })
})
```

### 最佳实践

1. **测试隔离**: 每个测试用例应该独立运行
2. **数据管理**: 使用 fixtures 管理测试数据
3. **自定义命令**: 封装常用操作到自定义命令
4. **页面对象**: 使用页面对象模式组织测试代码

### 持续集成

在 CI/CD 环境中运行测试：

```yaml
# GitHub Actions 示例
- name: Run Cypress tests
  run: |
    pnpm build
    pnpm start &
    pnpm test
```

> 📚 **参考文档**: [Cypress 官方文档](https://docs.cypress.io/) | [Cypress 最佳实践](https://docs.cypress.io/guides/references/best-practices) | [Testing Library](https://testing-library.com/docs/)

## 👥 团队协作

### 分支策略

- `main` - 主分支，保护分支
- `develop` - 开发分支
- `feature/*` - 功能分支
- `hotfix/*` - 热修复分支

### 开发流程

1. 从 `develop` 分支创建功能分支
2. 开发完成后提交 Pull Request
3. 代码审查通过后合并到 `develop`
4. 定期将 `develop` 合并到 `main`

### 代码审查要点

- 代码是否符合项目规范
- 功能是否完整实现
- 是否有适当的测试
- 文档是否更新

> 📚 **参考文档**: [Git 分支策略](https://nvie.com/posts/a-successful-git-branching-model/) | [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)

## ❓ 常见问题

### Q: 如何添加新的页面？

A: 在 `app/` 目录下创建新的文件夹和 `page.tsx` 文件。

### Q: 如何添加新的组件？

A: 在 `components/` 目录下创建组件文件，使用 TypeScript 和函数式组件。

### Q: 提交时遇到格式错误怎么办？

A: 运行 `pnpm format` 和 `pnpm lint:fix` 修复问题，然后重新提交。

### Q: 如何添加新的依赖？

A: 使用 `pnpm add <package-name>` 添加依赖。

### Q: 如何运行测试？

A: 项目配置了 Cypress，可以使用以下命令：

- `pnpm test` - 运行所有测试
- `pnpm test:open` - 打开 Cypress 测试界面
- `pnpm test:component` - 仅运行组件测试
- `pnpm test:e2e` - 仅运行 E2E 测试

### Q: 如何调试测试失败？

A: 使用 `cypress open` 在浏览器中调试，查看详细的错误信息和截图。

## 🛠️ 开发脚本

```bash
# 开发相关
pnpm dev            # 启动开发服务器
pnpm build          # 构建生产版本
pnpm start          # 启动生产服务器

# 代码质量
pnpm lint           # 运行 ESLint 检查
pnpm lint:fix       # 运行 ESLint 检查并修复可以自动修复的问题
pnpm format         # 格式化代码

# 测试相关
pnpm test           # 运行所有测试
pnpm test:open      # 打开 Cypress 测试界面
pnpm test:install   # 初始化 Cypress
pnpm test:component # 仅运行组件测试
pnpm test:e2e       # 仅运行 E2E 测试

# Git 钩子
pnpm prepare      # 安装 Husky 钩子
```

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m ':sparkles: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

---

**Happy Coding!** 🎉