fischerX/docs/development/troubleshooting.md

常见问题解答

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

目录

• 环境问题
• 构建问题
• 运行时问题
• 调试技巧

---

环境问题

Node.js 版本不匹配

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

解决方案:

# 使用 fnm 安装正确版本
fnm install 20
fnm use 20

# 或使用 nvm
nvm install 20
nvm use 20

pnpm 未找到

问题: command not found: pnpm

解决方案:

# 安装 pnpm
npm install -g pnpm@8

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

依赖安装失败

问题: pnpm install 失败或超时

解决方案:

# 配置国内镜像源
pnpm config set registry https://registry.npmmirror.com

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

Docker 服务无法启动

问题: docker-compose up 失败

解决方案:

# 检查 Docker 是否运行
docker ps

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

# 重新启动
docker-compose up -d

# 查看日志
docker-compose logs

---

构建问题

Turborepo 缓存问题

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

解决方案:

# 清除 Turborepo 缓存
rm -rf .turbo

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

TypeScript 类型错误

问题: 构建时报 TypeScript 错误

解决方案:

1. 检查类型定义是否正确
2. 运行 pnpm lint 检查
3. 清除缓存：

rm -rf node_modules/.cache

Prisma Client 未生成

问题: 提示找不到 Prisma Client

解决方案:

# 进入 API 服务目录
cd services/api

# 生成 Prisma Client
pnpm prisma generate

# 运行迁移
pnpm prisma migrate dev

---

运行时问题

数据库连接失败

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

解决方案:

1. 检查数据库是否运行
2. 检查 .env 文件中的 DATABASE_URL 配置
3. 测试连接：

# 使用 Prisma 测试连接
cd services/api
pnpm prisma db pull

端口被占用

问题: EADDRINUSE: address already in use

解决方案:

# 查找占用端口的进程
lsof -ti :3000 | xargs kill -9  # macOS/Linux

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

环境变量未生效

问题: 环境变量值不正确

解决方案:

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

---

调试技巧

前端调试

1. 使用 React DevTools

   • 安装浏览器扩展
   • 检查组件树和 Props

2. 使用 console.log

console.log('Debug:', { user, state });

3. 使用 debugger

debugger; // 浏览器会在断点处暂停

后端调试

1. 使用 NestJS 调试模式

pnpm start:debug

2. 查看日志

// 在代码中添加日志
import { Logger } from '@nestjs/common';

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

数据库调试

1. 使用 Prisma Studio

cd services/api
pnpm prisma studio

2. 直接查询数据库

# 连接到 PostgreSQL
docker exec -it <container-name> psql -U postgres

---

下一步

• 贡献指南 - 了解如何贡献

---

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