ProductReadyProductReady

故障排查

常见问题及其解决方法 - 快速解决卡点

故障排查

遇到问题了？本指南涵盖常见问题及其解决方案。

找不到您的问题？ 搜索 GitHub Issues 或在 Discussions 中提问。

安装问题

pnpm install 后"Module not found"（未找到模块）

症状：导入错误，TypeScript 找不到模块

解决方案：

# 清除所有内容并重新安装
rm -rf node_modules .next pnpm-lock.yaml
pnpm install

# 重启开发服务器
pnpm dev

"pnpm not found"（未找到 pnpm）

解决方案：全局安装 pnpm

npm install -g pnpm

# 或使用 Corepack（推荐）
corepack enable
corepack prepare pnpm@latest --activate

"Node version too old"（Node 版本过旧）

症状：构建失败并出现语法错误

解决方案：升级到 Node.js 24.18.0 LTS

# 检查当前版本
node -v

# 安装最新 LTS（使用 nvm）
nvm install --lts
nvm use --lts

数据库问题

"Database connection failed"（数据库连接失败）

检查这些：

  1. PG_DATABASE_URL 是否已设置？

    echo $PG_DATABASE_URL
# 应显示：postgresql://...

  2. 格式是否正确？

    # 正确格式：
******host:5432/database

  3. 能否手动连接？

    psql $PG_DATABASE_URL
# 应无错误连接

  4. 数据库是否在运行？

    # 对于本地 Postgres
brew services list  # macOS
systemctl status postgresql  # Linux

"relation does not exist"（关系不存在）

原因：表未创建

解决方案：运行迁移

pnpm db:migrate

"Too many clients"（客户端过多）（Vercel/无服务器）

原因：未使用连接池

解决方案：使用池化连接字符串

Neon - 将端口从 5432 改为 6543：

# 之前
******host:5432/db

# 之后（池化）
******host:6543/db

Supabase - 使用仪表板中的"Connection pooling"（连接池）字符串

构建和 TypeScript 错误

"Type error: Cannot find module '~/...'"（类型错误：找不到模块）

原因：路径别名未配置

解决方案：检查 tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

更改后重启编辑器！

"Property 'X' does not exist on type 'Y'"（属性不存在于类型）

常见原因：

  1. 拼写错误 - 检查拼写
  2. 类型缺失 - 架构更改后运行 pnpm db:generate
  3. 类型过时 - 重启 TypeScript 服务器（VS Code：Cmd+Shift+P → "Restart TS Server"）

构建失败并出现"ReferenceError: X is not defined"

原因：在客户端组件中使用仅限 Node.js 的代码

解决方案：

// ❌ 错误 - fs 在客户端不可用
'use client';
import fs from 'fs';

// ✅ 正确 - 在服务器组件中使用
// app/page.tsx（无 'use client'）
import fs from 'fs';

export default function Page() {
  const data = fs.readFileSync('data.txt');
  // ...
}

认证问题

OAuth 重定向到错误的 URL

症状：GitHub/Google 登录后，重定向到 localhost

解决方案：检查环境变量

# 必须匹配您的实际域名
BETTER_AUTH_URL=https://your-app.vercel.app
NEXT_PUBLIC_APP_URL=https://your-app.vercel.app

在 Vercel 中：Project Settings → Environment Variables → 更新 → Redeploy

"Invalid client_id"（客户端 ID 无效）

GitHub OAuth：

  1. 前往 GitHub → Settings → Developer settings → OAuth Apps
  2. 检查 Authorization callback URL： 
    https://your-app.com/api/auth/callback/github
  3. 确保 Client ID/Secret 在 Vercel 环境变量中

Google OAuth：

  1. Google Cloud Console → APIs & Services → Credentials
  2. 添加 Authorized redirect URIs： 
    https://your-app.com/api/auth/callback/google

会话立即过期

原因：Cookie 设置问题

解决方案：检查 src/lib/auth.ts：

export const auth = betterAuth({
  // ...
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 天
    updateAge: 60 * 60 * 24, // 1 天
  },
  advanced: {
    cookiePrefix: "productready",
    useSecureCookies: process.env.NODE_ENV === "production",
  },
});

样式问题

Tailwind 类不起作用

原因：未配置 Tailwind

解决方案：检查 tailwind.config.ts：

export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    // 确保包含所有组件路径
  ],
  // ...
}

深色模式不工作

检查：

  1. Provider 已设置？

    // app/layout.tsx
import { ThemeProvider } from "next-themes";

<ThemeProvider attribute="class">
  {children}
</ThemeProvider>

  2. CSS 变量已定义？

    /* global.css */
.dark {
  --background: 0 0% 3.9%;
  --foreground: 0 0% 98%;
}

组件看起来损坏

原因：缺少 KUI 样式

解决方案：确保导入 KUI 样式：

// app/layout.tsx
import "kui/styles.css";

部署问题

Vercel 构建失败

检查构建日志：Deployments → 点击失败的部署 → Build Logs

常见修复：

"Module not found in production"

# 确保依赖在 dependencies 中（不是 devDependencies）
pnpm add package-name
# 不要用 pnpm add -D

"Build exceeded maximum duration"（构建超过最大持续时间）

# 优化构建
# 1. 移除未使用的依赖
pnpm prune

# 2. 使用更少的预构建步骤
# 3. 考虑升级 Vercel 计划

环境变量未设置

症状：生产环境缺少 env 变量

解决方案：

  1. Vercel → Project Settings → Environment Variables
  2. 为 Production、Preview 和 Development 添加所有变量
  3. 点击 Save（保存）
  4. Redeploy

API 路由返回 404

检查：

  1. 文件命名：必须是 route.ts（不是 index.ts）

    ✅ app/api/hello/route.ts
❌ app/api/hello/index.ts

  2. 导出方法：

    // ✅ 正确
export async function GET() { }
export async function POST() { }

// ❌ 错误
export default function handler() { }

性能问题

开发服务器慢

优化：

# 1. 清除 Next.js 缓存
rm -rf .next

# 2. 使用 Turbopack（实验性）
pnpm dev --turbo

# 3. 增加 Node 内存
NODE_OPTIONS='--max-old-space-size=4096' pnpm dev

生产构建慢

优化导入：

// ❌ 慢 - 导入整个库
import _ from 'lodash';

// ✅ 快 - 仅导入需要的
import debounce from 'lodash/debounce';

分析包大小：

pnpm build
# 查看输出中的"Page Size"

# 或使用包分析器
pnpm add -D @next/bundle-analyzer

tRPC 问题

"No mutation found"（未找到 mutation）

原因：路由器未导出

解决方案：检查 src/server/root.ts：

import { tasksRouter } from './routers/tasks';

export const appRouter = router({
  tasks: tasksRouter, // ← 确保已添加
});

类型不匹配

原因：客户端/服务器类型不同步

解决方案：

# 重启开发服务器
pnpm dev

# 或重启 TypeScript
# VS Code: Cmd+Shift+P → "Restart TS Server"

"Too many requests"（请求过多）

原因：无限循环查询

检查：

// ❌ 危险 - 在 useEffect 中无限循环
useEffect(() => {
  trpc.users.list.useQuery(); // 无限调用！
}, []);

// ✅ 正确
const { data } = trpc.users.list.useQuery();

Drizzle ORM 问题

"Prepared statement already exists"（准备语句已存在）

原因：连接池问题

解决方案：使用单例模式：

// src/db/index.ts
declare global {
  var db: ReturnType<typeof drizzle> | undefined;
}

export const db = global.db || drizzle(/* ... */);

if (process.env.NODE_ENV !== 'production') {
  global.db = db;
}

迁移不运行

检查：

  1. 迁移文件夹：

    ls drizzle/migrations/
# 应该显示 .sql 文件

  2. 数据库连接：

    echo $PG_DATABASE_URL

  3. 手动运行：

    pnpm db:migrate

开发体验

VS Code 自动完成不工作

解决方案：

  1. 安装扩展：

  2. 重启 TS 服务器：

    • Cmd+Shift+P → "TypeScript: Restart TS Server"

  3. 检查 tsconfig.json：

    {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

热重载不工作

原因：文件监视器限制（Linux）

解决方案：

# 增加 inotify 限制
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

端口已在使用

症状：Error: listen EADDRINUSE: address already in use :::3000

解决方案：

# 找到进程
lsof -i :3000

# 终止它
kill -9 <PID>

# 或使用不同的端口
PORT=3001 pnpm dev

Git 问题

无法推送（文件过大）

症状：remote: error: File is XXX MB; this exceeds GitHub's file size limit

解决方案：

# 从 Git 历史中移除大文件
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch path/to/large/file" \
  --prune-empty --tag-name-filter cat -- --all

# 强制推送
git push origin --force --all

合并冲突

解决方案：

# 更新主分支
git fetch origin main
git merge origin/main

# 解决冲突，然后：
git add .
git commit -m "Resolve merge conflicts"
git push

还是卡住了？

清除所有缓存

核选项 - 清除一切并重新开始：

# 清除所有缓存
rm -rf node_modules
rm -rf .next
rm -rf .turbo
rm pnpm-lock.yaml

# 重新安装
pnpm install

# 重新生成数据库类型
pnpm db:generate

# 重新启动
pnpm dev

获取帮助

如果仍然有问题：

  1. 搜索现有问题：GitHub Issues

  2. 创建新问题：包括：

    • 错误消息
    • 您的环境（Node 版本、OS）
    • 重现步骤
    • 相关代码片段

  3. 社区：GitHub Discussions

预防提示

避免常见问题：

✅ 应该做

  • 定期更新：pnpm update
  • 提交 lockfile：始终提交 pnpm-lock.yaml
  • 使用 TypeScript：尽早捕获错误
  • 添加测试：防止回归
  • 版本控制：频繁提交
  • 文档更改：在 README 或代码注释中

❌ 不应该做

  • 不要提交 .env 文件
  • 不要跳过类型检查
  • 不要忽略控制台警告
  • 不要在生产中使用 pnpm db:push
  • 不要在没有备份的情况下删除数据库

准备好继续构建了吗？希望这有帮助！ 🚀

演示模式

无需登录即可试用 ProductReady - 使用示例数据探索功能

On this page

故障排查安装问题pnpm install 后"Module not found"（未找到模块）"pnpm not found"（未找到 pnpm）"Node version too old"（Node 版本过旧）数据库问题"Database connection failed"（数据库连接失败）"relation does not exist"（关系不存在）"Too many clients"（客户端过多）（Vercel/无服务器）构建和 TypeScript 错误"Type error: Cannot find module '~/...'"（类型错误：找不到模块）"Property 'X' does not exist on type 'Y'"（属性不存在于类型）构建失败并出现"ReferenceError: X is not defined"认证问题OAuth 重定向到错误的 URL"Invalid client_id"（客户端 ID 无效）会话立即过期样式问题Tailwind 类不起作用深色模式不工作组件看起来损坏部署问题Vercel 构建失败环境变量未设置API 路由返回 404性能问题开发服务器慢生产构建慢tRPC 问题"No mutation found"（未找到 mutation）类型不匹配"Too many requests"（请求过多）Drizzle ORM 问题"Prepared statement already exists"（准备语句已存在）迁移不运行开发体验VS Code 自动完成不工作热重载不工作端口已在使用Git 问题无法推送（文件过大）合并冲突还是卡住了？清除所有缓存获取帮助预防提示✅ 应该做❌ 不应该做