fischerX/docs/development/troubleshooting.md

# 常见问题解答

> **文档版本**: v1.0.0
> **创建日期**: 2026-05-25
> **适用范围**: FischerX 项目开发人员

## 目录

- [环境问题](#环境问题)
- [构建问题](#构建问题)
- [运行时问题](#运行时问题)
- [调试技巧](#调试技巧)

---

## 环境问题

### Node.js 版本不匹配

**问题**: 运行 `pnpm install` 时提示 Node.js 版本不兼容

**解决方案**:
```bash
# 使用 fnm 安装正确版本
fnm install 20
fnm use 20

# 或使用 nvm
nvm install 20
nvm use 20
```

### pnpm 未找到

**问题**: `command not found: pnpm`

**解决方案**:
```bash
# 安装 pnpm
npm install -g pnpm@8

# 或使用官方脚本
curl -fsSL https://get.pnpm.io/install.sh | sh
```

### 依赖安装失败

**问题**: `pnpm install` 失败或超时

**解决方案**:
```bash
# 配置国内镜像源
pnpm config set registry https://registry.npmmirror.com

# 清除缓存重新安装
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### Docker 服务无法启动

**问题**: `docker-compose up` 失败

**解决方案**:
```bash
# 检查 Docker 是否运行
docker ps

# 停止并清理旧容器
docker-compose down
docker-compose rm -f

# 重新启动
docker-compose up -d

# 查看日志
docker-compose logs
```

---

## 构建问题

### Turborepo 缓存问题

**问题**: 构建时使用了旧的缓存导致错误

**解决方案**:
```bash
# 清除 Turborepo 缓存
rm -rf .turbo

# 或使用 --force 选项
pnpm build --force
```

### TypeScript 类型错误

**问题**: 构建时报 TypeScript 错误

**解决方案**:
1. 检查类型定义是否正确
2. 运行 `pnpm lint` 检查
3. 清除缓存：
```bash
rm -rf node_modules/.cache
```

### Prisma Client 未生成

**问题**: 提示找不到 Prisma Client

**解决方案**:
```bash
# 进入 API 服务目录
cd services/api

# 生成 Prisma Client
pnpm prisma generate

# 运行迁移
pnpm prisma migrate dev
```

---

## 运行时问题

### 数据库连接失败

**问题**: 应用无法连接到数据库

**解决方案**:
1. 检查数据库是否运行
2. 检查 `.env` 文件中的 `DATABASE_URL` 配置
3. 测试连接：
```bash
# 使用 Prisma 测试连接
cd services/api
pnpm prisma db pull
```

### 端口被占用

**问题**: `EADDRINUSE: address already in use`

**解决方案**:
```bash
# 查找占用端口的进程
lsof -ti :3000 | xargs kill -9  # macOS/Linux

# 或修改端口配置
# 在 apps/web/.env 中修改 PORT=3001
```

### 环境变量未生效

**问题**: 环境变量值不正确

**解决方案**:
1. 确保 `.env` 文件在正确位置
2. 重新启动开发服务器
3. 检查变量名拼写

---

## 调试技巧

### 前端调试

1. **使用 React DevTools**
   - 安装浏览器扩展
   - 检查组件树和 Props

2. **使用 console.log**
```tsx
console.log('Debug:', { user, state });
```

3. **使用 debugger**
```tsx
debugger; // 浏览器会在断点处暂停
```

### 后端调试

1. **使用 NestJS 调试模式**
```bash
pnpm start:debug
```

2. **查看日志**
```typescript
// 在代码中添加日志
import { Logger } from '@nestjs/common';

private readonly logger = new Logger(UserService.name);
this.logger.log('User created', userId);
```

### 数据库调试

1. **使用 Prisma Studio**
```bash
cd services/api
pnpm prisma studio
```

2. **直接查询数据库**
```bash
# 连接到 PostgreSQL
docker exec -it <container-name> psql -U postgres
```

---

## 下一步

- [贡献指南](./contributing.md) - 了解如何贡献

---

> **文档维护**: 本文档由开发团队维护，如有问题或建议请提交 Issue。
> **最后更新**: 2026-05-25