常见问题与排障清单

TL;DR（Top 10 快查）

1. .env.local 缺失或 DATABASE_URL 未填 → 复制模板并填写连接串
2. Prisma 生成失败 → bunx prisma generate 后再 init
3. 端口占用 → PORT=3001 bun dev
4. 登录 403/404 → Action 前缀不对或角色未绑定权限
5. 菜单不显示 → 菜单 path 不匹配页面路由
6. 列表空白 → fieldsConfig 的 key 与数据库字段不一致
7. 表单不显示字段 → 被 hidden/disabled 或类型不受支持
8. 批量操作无效 → 未提供对应 actions 或未开启开关
9. next build 报 ESLint/TS → 先修复类型/语法问题
10. 外链图片 403 → 使用普通 img（本项目已处理）

按启动 → 数据库 → 权限 → 组件 → 构建的顺序排查，先覆盖基础依赖与环境变量。

启动失败 / 依赖问题

• 确认 Node.js 20.9+，本地包管理器用 bun install 或 pnpm install 重新装依赖。
• .env.local 是否存在且被 bun run init 读取；缺少 DATABASE_URL 会直接中断。
• 端口占用：默认 3000，冲突时用 PORT=3001 bun dev。
• macOS/Linux 没有执行权限时，给脚本加 chmod +x scripts/*.sh。

数据库 / Prisma

• 连接错误：用 psql $DATABASE_URL 或 bun prisma db push 验证连接，云数据库需要允许公网/白名单。
• 迁移失败：删除 .prisma 缓存、重新 bun prisma generate，再执行 bun run init；若 schema 变更，先清理历史迁移或重建库。
• 种子数据缺失：确认 bun run init 完整跑完 4 步；若只想导入种子，可执行 bun run seed（需先生成 Prisma Client）。

登录 / 权限 / 菜单

• 后台登录跳转失败：检查 BETTER_AUTH_URL 与实际访问域名一致（含协议端口），BETTER_AUTH_SECRET 至少 32 字节。
• 403/404：确认 Action 名称前缀是否为 sys，并在角色里绑定对应权限与菜单；RBAC 缺少权限时会直接返回 404。
• 菜单不显示：menu.path 需与页面实际路由一致；如果是外链或自定义页，保持唯一 path 并勾选关联的权限码。

SmartCrudPage / SmartForm

• 列表空白或报错：fieldsConfig 中的 key 必须与数据库字段一致；actions.getList 等函数要全部传入。
• 表单不渲染字段：form.hidden/form.disabled 是否被配置，或字段类型不受支持（参考 /docs/api/FIELDS_CONFIG）。
• 批量操作/自定义按钮无效：确认 actions 中提供对应处理函数，并在组件上开启 enableBatchActions 等开关。

构建 / 运行

• next build 报错：优先检查未处理的 TypeScript/ESLint 问题；MDX 错误通常是导入路径不对或含有未支持的语法。
• 静态资源 404：确保文件放在 public/ 下且引用路径以 / 开头；云存储相关配置需在 .env.local 完整配置（参考 /docs/admin/guides/STORAGE）。
• 国际化路由问题：访问路径中带上 locale（例如 /zh/admin），并检查 i18n/config 的默认语言设置。

仍未解决？

• 按模块定位：数据库相关去看 /docs/admin/database/PRISMA_GUIDE；权限问题结合 /docs/architecture/PERMISSION_MODEL 与 /docs/admin/rbac/CONFIGURATION。
• 提交 Issue 时附上：执行命令、终端完整报错、.env.local 关键配置（脱敏）、Prisma 版本与数据库类型。