zetaloop
197 lines
4.6 KiB
Markdown
197 lines
4.6 KiB
Markdown
# 聚玩前端
|
||
|
||
基于 Next.js 15 的游戏代练平台前端应用。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Next.js 15 (App Router)
|
||
- **语言**: TypeScript
|
||
- **样式**: Tailwind CSS 4
|
||
- **状态管理**: Zustand
|
||
- **表单**: React Hook Form + Zod
|
||
- **UI 组件**: Radix UI + shadcn/ui
|
||
- **测试**: Vitest
|
||
|
||
## 开发环境设置
|
||
|
||
### 前置要求
|
||
|
||
- Node.js 20+
|
||
- pnpm 9+
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 连接后端开发
|
||
|
||
1. **启动后端服务**
|
||
|
||
后端使用 Kubernetes 部署，需要先启动后端集群（参考后端仓库的部署文档）。
|
||
|
||
2. **配置端口转发**
|
||
|
||
将后端 Envoy Gateway 转发到本地：
|
||
|
||
```bash
|
||
kubectl port-forward -n juwan svc/envoy-gateway 8080:80
|
||
```
|
||
|
||
3. **配置环境变量**
|
||
|
||
创建 `.env.local` 文件：
|
||
|
||
```bash
|
||
# 后端 API 地址（通过 kubectl port-forward 转发）
|
||
NEXT_PUBLIC_BACKEND_URL=http://localhost:8080
|
||
|
||
```
|
||
|
||
4. **启动前端开发服务器**
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
访问 http://localhost:3000
|
||
|
||
**工作原理**：
|
||
- 前端向 `/api/*` 发起请求
|
||
- Next.js dev server 自动将请求代理到 `http://localhost:8080/api/*`
|
||
- 后端通过 `kubectl port-forward` 接收请求
|
||
- 无需修改前端代码中的 API 调用路径
|
||
|
||
### 其他命令
|
||
|
||
```bash
|
||
# 类型检查
|
||
pnpm typecheck
|
||
|
||
# 代码检查
|
||
pnpm lint
|
||
|
||
# 代码格式化
|
||
pnpm format
|
||
|
||
# 运行测试
|
||
pnpm test
|
||
|
||
# 完整检查（类型 + lint + 格式）
|
||
pnpm check
|
||
|
||
# 生产构建
|
||
pnpm build
|
||
|
||
# 启动生产服务器
|
||
pnpm start
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
juwan-frontend/
|
||
├── app/ # Next.js App Router 页面
|
||
│ ├── (auth)/ # 认证相关页面（注册/登录/找回密码）
|
||
│ ├── (account)/ # 账户相关页面（个人中心/认证申请）
|
||
│ ├── (order)/ # 订单相关页面（下单/聊天/评价/纠纷）
|
||
│ └── (main)/ # 主要页面（首页/搜索/打手/店铺）
|
||
├── components/ # 可复用组件
|
||
├── lib/ # 工具函数和类型定义
|
||
│ ├── api/ # API 调用函数
|
||
│ ├── domain/ # 业务逻辑（状态机等）
|
||
│ ├── types.ts # 核心类型定义
|
||
│ ├── errors.ts # 错误处理
|
||
│ └── decision.ts # 权限决策
|
||
├── store/ # Zustand 状态管理
|
||
├── tests/ # 测试文件
|
||
└── public/ # 静态资源
|
||
|
||
```
|
||
|
||
## API 代理配置说明
|
||
|
||
开发环境下，Next.js 会自动将 `/api/*` 请求代理到后端：
|
||
|
||
```typescript
|
||
// next.config.ts
|
||
async rewrites() {
|
||
if (process.env.NODE_ENV !== 'development') {
|
||
return []
|
||
}
|
||
const backendUrl = process.env.NEXT_PUBLIC_BACKEND_URL || 'http://localhost:8080'
|
||
return [
|
||
{
|
||
source: '/api/:path*',
|
||
destination: `${backendUrl}/api/:path*`,
|
||
},
|
||
]
|
||
}
|
||
```
|
||
|
||
**优点**：
|
||
|
||
- 前端代码无需关心后端地址
|
||
- 避免 CORS 问题（同源请求）
|
||
- Cookie 自动携带
|
||
- 开发/生产环境无缝切换
|
||
|
||
## 环境变量
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
| ------------------------- | ------------------------------- | ----------------------- |
|
||
| `NEXT_PUBLIC_BACKEND_URL` | 后端 API 地址（仅开发环境生效） | `http://localhost:8080` |
|
||
|
||
**注意**：
|
||
|
||
- 此变量仅在开发环境（`pnpm dev`）生效，用于配置 API 代理目标
|
||
- 生产环境不使用此变量，前后端通过 Envoy Gateway 统一路由
|
||
|
||
## 部署
|
||
|
||
### 构建 Docker 镜像
|
||
|
||
```bash
|
||
docker build -t juwan-frontend:latest .
|
||
docker tag juwan-frontend:latest 103.236.53.208:4418/library/juwan-frontend:latest
|
||
docker push 103.236.53.208:4418/library/juwan-frontend:latest
|
||
```
|
||
|
||
### 部署到 Kubernetes
|
||
|
||
```bash
|
||
kubectl apply -f deploy/k8s/frontend.yaml
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
- 使用 TypeScript 严格模式
|
||
- 遵循 ESLint 规则（`pnpm lint`）
|
||
- 提交前运行 `pnpm check` 确保代码质量
|
||
- 所有 API 调用必须有类型定义
|
||
- 组件使用 shadcn/ui 风格
|
||
|
||
## 常见问题
|
||
|
||
### Q: 本地开发如何连后端？
|
||
|
||
A: 按照 开发环境设置 里的步骤完成 `kubectl port-forward`，并在 `.env.local` 配置 `NEXT_PUBLIC_BACKEND_URL`。前端统一请求 `/api/*`，开发环境由 Next.js 代理到本地转发端口。
|
||
|
||
### Q: 后端连接失败怎么办？
|
||
|
||
A: 检查以下几点：
|
||
|
||
1. 后端 K8s 集群是否正常运行
|
||
2. `kubectl port-forward` 是否在运行
|
||
3. `.env.local` 中的 `NEXT_PUBLIC_BACKEND_URL` 是否正确
|
||
4. 浏览器控制台是否有 CORS 错误
|
||
|
||
### Q: 如何添加新的 API？
|
||
|
||
A:
|
||
|
||
1. 在 `lib/types.ts` 定义类型
|
||
2. 在 `lib/api/` 创建 API 函数
|
||
3. 在 `store/` 中调用 API
|