求助问答

next/image 图片模糊或变形，检查：① 是否设置了 width/height 或 fill ② fill 模式需要父容器 position: relative ③ priority 只给 LCP 图片 ④ sizes 属性帮助浏览器选择正确尺寸 ⑤ 避免在 Server Component...

next-intl 配置后 404，一般是 middleware 匹配规则不对。检查 middleware.ts 中 matcher 配置，确保排除了 /api、/_next、/admin 等非国际化路径。另外检查 defaultLocale 和 locales 配置是否正确。 Prisma 多对...

React Server Component 中使用 useState 报错，因为 Server Component 不能用 hooks。解决：① 把需要状态的组件拆成 Client Component（加 'use client'） ② 父组件保持 Server Component 做数据获取，子...

router.push 不更新 URL，Next.js 15 + next-intl 在 useSession 触发 re-render 时可能取消 router.push 的 startTransition。解决：用 window.location.href 硬导航（认证流程的例外允许裸路径）。...

Auth.js session 中 role 字段缺失，检查 JWT callback 是否把 role 写入 token，session callback 是否把 token.role 写入 session.user.role。两步缺一不可。 Prisma $queryRaw 中 camelCa...

Prisma 索引没生效查询慢，确认：① 查询条件字段是否建了 @@index ② 迁移是否执行 ③ 用 EXPLAIN ANALYZE 查看执行计划 ④ 是否有函数索引需求 ⑤ 大表考虑分区。 Zod 校验错误消息不显示，检查：① form 表单是否关联了错误状态 ② Zod schema 的错...

revalidateTag vs revalidatePath：revalidateTag 清除特定 tag 的缓存（fetch 时用 next.tags 标记），revalidatePath 清除特定路径的缓存。数据变更后 revalidatePath 更直接，精细控制用 revalidateTa...

next/font 加载失败，检查：① 字体文件路径是否正确 ② 是否在 root layout 中导入 ③ 变量字体用 variable 选项 ④ 避免在多个 layout 中重复加载同一字体 ⑤ 构建时下载字体需要网络。 Auth.js credentials 登录返回 null，检查：① a...

Prisma $transaction 超时回滚，默认超时 5s。长事务用 $transaction(async (tx) => { ... }, { timeout: 30000 }) 设置超时。Serverless 环境注意函数超时限制。 Next.js 15 中 next/dynamic +...

Zod refine 校验不触发，检查：① refine 是否在 schema 末尾 ② 是否用了 safeParse（parse 会抛错） ③ refine 的 path 是否正确指向字段 ④ 异步 refine 用 superRefine + async。 middleware 重定向循环，一...

Prisma $transaction 超时回滚，默认超时 5s。长事务用 $transaction(async (tx) => { ... }, { timeout: 30000 }) 设置超时。Serverless 环境注意函数超时限制。 Prisma $queryRaw 中 camelCas...

Next.js 15 中 cookies().set() 后跟 redirect() 不兼容，因为 redirect() 抛出特殊错误终止请求，不会包含之前设置的 cookie。解决：用 Server Action（cookies().set 在 Action 中正常工作）或渲染客户端组件处理。...

Auth.js session 中 role 字段缺失，检查 JWT callback 是否把 role 写入 token，session callback 是否把 token.role 写入 session.user.role。两步缺一不可。 Vercel 部署后 CSS 丢失，常见原因：① T...

Server Action 提交后不跳转，可能是用了 router.push 而非 window.location.href。Next.js 15 + next-intl 的 router.push 在 startTransition 内会被 toast 的状态更新中断。解决：用 window.lo...

router.push 不更新 URL，Next.js 15 + next-intl 在 useSession 触发 re-render 时可能取消 router.push 的 startTransition。解决：用 window.location.href 硬导航（认证流程的例外允许裸路径）。...

Prisma $transaction 超时回滚，默认超时 5s。长事务用 $transaction(async (tx) => { ... }, { timeout: 30000 }) 设置超时。Serverless 环境注意函数超时限制。 Prisma 事务中 create 返回的 id 在...

next/image 图片模糊或变形，检查：① 是否设置了 width/height 或 fill ② fill 模式需要父容器 position: relative ③ priority 只给 LCP 图片 ④ sizes 属性帮助浏览器选择正确尺寸 ⑤ 避免在 Server Component...

Next.js middleware 中 pathname 精确匹配失效，因为 intl 中间件处理后 pathname 含 locale 前缀（如 /zh/dashboard）。用 pathname.includes() 或 getLocaleFromPathname() 而非 pathname...

router.push 不更新 URL，Next.js 15 + next-intl 在 useSession 触发 re-render 时可能取消 router.push 的 startTransition。解决：用 window.location.href 硬导航（认证流程的例外允许裸路径）。...

Auth.js JWT token 中字段不更新，因为 JWT 是有状态的快照。修改用户字段后需要用 useSession().update() 刷新客户端 session，同时 JWT callback 中处理 trigger === 'update' 从 DB 读取最新值更新 token。 P...