Next.js

Next.js 是最流行的 React 全栈框架。它让同一个项目里既有界面，也有服务端代码：页面可以在服务器上渲染好再发给浏览器，也可以在构建时生成静态页面。

为什么是备选而不是首选

能力越多，需要理解的概念也越多：服务端组件和客户端组件的边界、数据缓存、静态与动态渲染……AI 在这些边界上最容易出错——比如在服务端组件里用了浏览器 API，或者让本该静态的页面变成每次请求都渲染。对“会一点代码”的人，排查这类问题的成本很高。

所以我们的建议是：先用 Vite + React，遇到下面这些需求再换 Next.js。

什么时候值得选它

• 搜索引擎收录和首屏速度很重要。 服务端渲染让内容直接出现在 HTML 里。
• 需要服务端逻辑，又不想单独维护一个后端。 接口、表单处理、访问数据库都可以写在同一个项目里。
• 内容多、页面多。 按文件组织的路由和构建时生成静态页面很省心。

顺带一提，你正在看的这个网站就是用 Next.js 做的：它是一个需要按语言生成大量静态页面的内容站，正好落在上面的适用范围里。

让 AI 少踩坑

在 AGENTS.md 里写明服务端和客户端的边界（见纪念品），并要求 AI 改动后运行一次生产构建——很多问题只在构建时才会暴露。

# AGENTS.md（Next.js 部分）

## 命令
- 开发：`pnpm dev`
- 生产构建：`pnpm build`（改动路由、数据获取或配置后必须运行）
- 全部检查：`pnpm check`

## 服务端与客户端
- 组件默认是服务端组件。只有用到状态、事件处理或浏览器 API 时，才在文件顶部加 `'use client'`。
- `'use client'` 尽量放在组件树的叶子上，不要给整页加。
- 不要在服务端组件里使用 `window`、`document`、`localStorage`。
- 密钥只在服务端使用；暴露给浏览器的环境变量必须以 `NEXT_PUBLIC_` 开头。

## 数据与渲染
- 能在构建时生成的页面保持静态；需要按请求渲染时说明理由。
- 服务端接口校验所有输入，返回明确的错误状态码。

## 结构
- 路由在 `app/` 下；业务逻辑放在 `src/features/`，页面文件只做组装。