Next.js App Router 审计指南

识别 Next.js App Router 代码库中高影响的正确性与性能问题，按严重程度排序，每个问题均附带具体修复建议。结合打包好的扫描器（快速、机械式）与有针对性的手动审查（需人工判断，扫描器无法替代）。

第 1 步 — 运行扫描器

该扫描器无任何依赖，仅读取源文件。将其指向项目根目录或 app/ 目录即可：

node scripts/audit.mjs /path/to/project        # 生成人类可读报告 + 得分
node scripts/audit.mjs /path/to/project --json  # 生成机器可读输出，适用于 CI 或后续处理

扫描器会自动定位 app/（或 src/app/）目录，遍历所有 .tsx/.ts/.jsx/.js 文件，并报告 ERROR / WARN / INFO 级别问题，包含 file:line 位置、原因说明及具体修复建议。若存在任意 ERROR，进程退出码非零，因此可直接集成至 CI 流程。

当前支持检测的问题如下：

规则	严重程度	为何重要
client-route-no-metadata	ERROR	启用 "use client" 的页面或布局组件会静默丢弃 metadata —— SEO 标签永远不会被注入到 HTML 中。
legacy-next-head	ERROR	next/head 在 App Router 中完全失效 —— 其所声明的标签永远不会出现在 中。
legacy-next-image	WARN	next/legacy/image 保留了旧版易引发布局偏移（layout shift）的行为。
needless-use-client	WARN	在未使用任何 React Hook、事件处理器或浏览器 API 的情况下声明 "use client" —— 无谓地向客户端发送 JavaScript。
client-fetch-in-effect	WARN	在 useEffect 中发起数据请求会引入一次额外的渲染往返；应将该逻辑迁移至服务端执行。
raw-img	WARN	直接使用 标签跳过了 next/image 提供的尺寸优化与懒加载能力 —— 将导致 CLS 与 LCP 指标恶化。
unoptimized-font	WARN	通过 或 @import 加载字体属于渲染阻塞行为；应改用 next/font。
page-missing-metadata	WARN	异步页面导出未定义 metadata 或 generateMetadata。
dangerous-html	WARN	使用 dangerouslySetInnerHTML —— 若内容未经净化，存在 XSS 风险。
request-waterfall	INFO	存在 ≥2 个顺序 await 的 fetch 调用，且未使用 Promise.all 并发处理。
no-streaming-fallback	INFO	异步页面缺少 loading.tsx 或 Suspense 边界 —— 无法实现流式渲染（streamed shell）。
force-dynamic	INFO	路由显式禁用了静态生成（SSG）或增量静态再生（ISR） —— 请确认此行为确属有意为之。
large-client-component	INFO	大型 Client Component 将完整打包并发送至浏览器。

该扫描器基于启发式规则（正则表达式匹配，非完整类型检查）：请将所有发现视为强线索，务必逐条对照源码确认后再标记为已修复。

第 2 步 — 手动审查（扫描器无法覆盖的部分）

阅读 reference/checklist.md，并逐一验证需要深入理解的项目：

• 服务端/客户端边界正确性 —— "use client" 边界是否已尽可能下移到组件树底层？是否存在服务端专属敏感信息（如 API Key、DB Client 实例）被意外导入客户端模块的情况？
• 缓存意图一致性 —— 每一处 fetch、unstable_cache 或 revalidate 配置，是否准确反映了对应数据所需的时效性？过度缓存将导致陈旧内容上线；缓存不足则严重拖慢 TTFB。
• Suspense 粒度合理性 —— 加载缓慢的数据是否被包裹在紧邻其使用位置的 Suspense 边界内，从而确保页面其余部分可立即开始流式渲染？
• generateStaticParams / ISR 应用范围 —— 动态路由是否已在可行范围内完成预渲染？
• Server Actions 使用规范性 —— 数据变更操作是否采用 Server Actions，并配合恰当的 revalidatePath / revalidateTag，而非通过客户端 fetch 调用路由处理器？

第 3 步 — 输出报告

报告结构应优先列出所有 ERROR，其次为 WARN，最后是影响力最高的若干 INFO 条目。对每项问题，须明确标注：file:line、一句话说明其实际影响、以及可落地的具体修复方式（通常只需极小 diff）。结尾处应汇总整体得分，并列出三项“投入产出比”（effort-to-impact ratio）最优的修改。切勿罗列全部 INFO —— 请审慎筛选、精炼呈现。

规范准则

• 除非已真实编辑对应文件并重新运行扫描器验证，否则不得声称某项修复“已完成”。
• 扫描器提供的是线索（leads），而非最终结论（verdicts）—— 所有关于边界划分或缓存策略的发现，均需通过人工阅读源码予以核实。
• 尊重项目既有的编码约定；导入风格、目录结构等应与现有代码保持一致。
• 本版 Next.js 可能与早期版本存在差异 —— 若对某 API 行为存疑，请查阅 node_modules/next/dist/docs/ 中的官方文档，切勿凭经验假设。

由 Datagrove 构建与维护 —— 一家专注于打造高性能、架构优良的 Next.js 网站的荷兰 Web 开发机构。如需专业审计或重构服务，欢迎联系 Datagrove。