常见问题 FAQ

开发过程中常见问题的排查与解决

构建问题

症状: Next.js 构建时出现 TypeScript 类型错误（如 No overload matches this call），但直接运行 tsc --noEmit 通过。

原因: Turbo 缓存了旧的构建产物，增量构建使用了过期缓存。

解决:

# 清除 turbo 缓存后重新构建（Turbo v2 没有 clean 命令，需手动删除缓存目录）
rm -rf .turbo node_modules/.cache/turbo
pnpm run build

如果仍然不行，完全清理：

rm -rf .turbo node_modules/.cache/turbo
rm -rf node_modules apps/web/node_modules packages/*/node_modules
pnpm install
pnpm run build

开发时修改了代码但页面没有变化，可能是 Next.js 本地缓存问题：

rm -rf apps/web/.next
pnpm dev

通常是路径别名或导入大小写问题。macOS 文件系统不区分大小写，但 Linux CI 环境区分：

# 检查导入路径大小写是否与文件名完全一致
# 错误: import { Foo } from '@/modules/Auth/...'
# 正确: import { Foo } from '@/modules/auth/...'

本项目使用 pnpm strict 模式，peer dependency 警告通常可以忽略。如果是 zod 相关的版本冲突，项目使用 zod@^4.x，部分依赖会同时引入 zod@3.x 作为传递依赖，这是正常的。

# 示例：给 apps/web 添加依赖
pnpm --filter @community/web add some-package

# 开发环境：直接推送 schema 变更
pnpm db:push

# 生产环境：创建迁移文件
pnpm db:migrate

# 修改 schema 后务必重新生成客户端
pnpm db:generate

# 查看当前 schema 与数据库的差异
pnpm db:push --dry-run

# 强制同步（会丢失数据，仅开发环境使用）
pnpm db:push --force-reset

# 使用其他端口
pnpm dev -- -p 3001

# 或者找到并关闭占用进程
lsof -i :3000

# 自动修复大部分 lint 问题
pnpm lint:fix

# 格式化代码
pnpm format

使用 Conventional Commits 格式：

feat(auth): 添加微信登录
fix(ui): 修复移动端导航栏溢出
docs: 更新开发指南
chore: 升级依赖版本