nextjs

Next.js

Next.js App Router（14+）的项目约定。编写或修改代码时请遵循这些约定——除非有人要求，否则不要迁移未改动的路由。

约定

• 仅使用 App Router。 永远不要向 pages/ 添加内容。如果项目中仍有该目录，新工作应放在 app/，两个目录共存，直到有人安排迁移。
• 默认使用 Server Components。 'use client' 用于标记需要交互功能的叶节点，而非页面。该标记上方的所有内容也会发送到浏览器，因此应尽可能将边界放在树的深处。
• 根据已安装的版本验证缓存行为——它变过。 在 Next 14 及之前，fetch 默认会缓存，需要显式选择退出；从 Next 15 开始，fetch、Route Handlers 和客户端导航默认不缓存，需要显式选择启用。如果假设了错误的默认行为，页面可能会显示过时内容，或导致源站处理每个请求。检查 package.json，然后明确设置意图（cache、next.revalidate 或路由段配置），不要依赖默认行为。
• 从 Next 15 开始，params 和 searchParams 是 Promise——const { slug } = await params。针对 14 编写的代码会同步解构它们，升级后就会出错，因此复制任一种写法前都要先检查已安装的主版本。
• layout.tsx 中的身份验证检查不是安全边界。 在子路由之间导航时，布局不会在每次导航时重新渲染，因此客户端导航可能跳过检查。应在中间件中强制执行访问控制，并在读取数据时再次检查；布局中的检查只是改善用户体验，并非强制措施。
• 为获取的数据添加标签，按标签重新验证。 next: { tags: ['user'] } 加上变更后的 revalidateTag('user')，可以准确地使受影响的数据失效。基于时间的重新验证只是对数据过时情况的估算；标签则准确反映了这一点。
• Server Actions 是公开端点。 任何找到 Action ID 的人都能访问它们，因此每个 Action 都必须重新检查身份验证，并在服务端重新验证输入。渲染它的表单并不能证明调用者的身份。
• 在渲染数据的组件中获取数据。 React 会在一次渲染过程中对相同请求去重，因此为了避免“重复”获取而通过 props 层层传递数据毫无益处，还会让组件树彼此耦合。
• 通过 Metadata API 设置元数据——使用 export const metadata 或 generateMetadata。组件中手写的 <head> 标签不会在嵌套布局间合并，而且会被框架生成的标签悄然覆盖。
• 始终使用 next/image 和 next/font。 它们分别解决了两项影响最大的 Core Web Vitals 问题：未指定尺寸的图片导致布局偏移，以及字体加载阻塞首次绘制。直接使用 <img> 会放弃这两项优化。
• 为每个有意义的路由段配置 loading.tsx 和 error.tsx。 路由边界是应该隔离错误的位置；没有 error.tsx 时，一个路由段的错误会导致周围的布局也无法使用。