# Next.js 精通 (v15/16 + React 19) 代码示例： * [examples-core.md]() — 组件、路由、数据获取、突变 * [examples-platform.md]() — 缓存、错误、身份验证、i18n、安全、代理 ## v14 的重大更改改变 |迁移 ---|--- fetch 默认情况下**不缓存** |选择加入：`cache: 'force-cache'` 或 `next: { revalidate: N }` 未缓存的 GET 路由处理程序 |选择加入：`export const dynamic = 'force-static'` params、searchParams 是 **Promises** |服务器组件中的“await params”，客户端组件中的“use(params)” cookies(), headers() 是 **异步** |必须“await”——v16 中删除了同步访问权限 `useFormState` 已弃用 |使用“react”中的“useActionState”（而不是“react-dom”） `middleware.ts` 已弃用 |重命名为 `proxy.ts`，导出 `proxy` 函数（在 Node.js 上运行，而不是 Edge） `next/image` `priority` 已弃用 |使用 `preload` 属性代替并行路由需要 `default.tsx` |如果没有它们，构建就会失败 - 添加到每个“@slot”目录 **迁移 codemod：** `npx @next/codemod@canary 中间件到代理。` ## 文件约定应用程序/ ├──layout.tsx # 共享包装器（跨导航持续存在） ├── template.tsx # 每次导航时重新安装 ├── page.tsx # 路线UI ├── loading.tsx # 悬念回退 ├── error.tsx # 错误边界（需要‘使用客户端’） ├── not-found.tsx # 404 UI ├── global-error.tsx # 根布局错误边界（必须包含 /） ├──route.ts # API端点（同一目录下没有page.tsx） ├── default.tsx # 并行路由回退（每个槽都需要） ├── opengraph-image.tsx # OG图像生成 └── proxy.ts # 网络代理（替换 middleware.ts） ## 模式 ### 1\.服务器组件（默认）用于数据获取、秘密、繁重计算。将慢速数据包装在“”中以进行流式传输。并置数据获取 — 在呈现数据的组件中获取。请参阅[示例：流式处理]()。 ### 2\.客户端组件添加“使用客户端”仅用于交互（挂钩、事件处理程序、浏览器 API）。使用“useActionState”作为服务器操作状态（替换“useFormState”）。使用 `use()` 来解包从服务器组件传递的 Promise。请参阅[示例：客户端]() 和[示例： use()]()。 ### 3\.服务器操作用“使用服务器”标记。使用 Zod 验证所有输入。在突变之前检查身份验证。以值的形式返回错误——不抛出预期的失败。突变后调用 `revalidateTag`/`revalidatePath`。请参阅[示例：操作]()。 ### 4\.路由处理程序每次 POST/PUT/DELETE 时都进行身份验证保护。请求正文上的 Zod 模式验证。返回正确的状态代码（201已创建、400错误请求、401未经授权、404未找到）。默认情况下，GET 处理程序是不缓存的。请参阅[示例：路由处理程序]()。 ### 5\.并行路线使用“@slot”目录来实现独立的加载状态。每个插槽**必须**具有“default.tsx”。每个槽通过自己的“loading.tsx”独立地进行流传输。请参阅[示例：并行]()。 ### 6\.拦截路线使用`(.)`前缀来拦截同级路由（模态）。提供全页回退以进行直接导航和刷新。始终在“@modal”槽中包含“default.tsx”。请参阅[示例：拦截]()。 ### 7\.元数据和搜索引擎优化使用“generateMetadata”获取动态每页元数据。使用“generateStaticParams”进行静态生成。当数据不存在时调用“notFound()”。请参阅[示例：元数据]()。 ## 缓存 ### 获取（v15+ 默认值） fetch 默认情况下是不缓存的。明确选择加入：图案|选项 ---|--- 未缓存（默认）| `获取（网址）` 静态| `fetch(url, { 缓存: '强制缓存' })` 情监侦 | `fetch(url, { next: { revalidate: 60 } })` 已标记 | `fetch(url, { next: { 标签: ['产品'] } })` ###“使用缓存”指令（v16）在“next.config.ts”中使用“cacheComponents: true”启用。替换“unstable_cache”。 * 应用在文件、组件或函数级别 * 使用“next/cache”中的“cacheLife()”和“cacheTag()”进行配置 * 无法在内部调用 `cookies()`/`headers()` — 作为参数传递 * 使用“updateTag()”（读取您的写入）或“revalidateTag()”使内容无效简介 |陈旧|重新验证 |过期 ---|---|---|--- `秒` | 30 多岁 | 1秒| 1分钟 `分钟` | 5分钟| 1 分钟 | 1小时 `小时` | 5分钟| 1 小时 | 1天 `天` | 5分钟| 1天 | 1周 `几周` | 5分钟| 1 周 | 30天 `最大` | 5分钟| 30 天 | 1年请参阅[示例：使用缓存]()。 ## 错误处理 * **预期错误** — 作为服务器操作的值返回（`{ message: "..." }`），而不是抛出 * **`error.tsx`** — 必须是“使用客户端”；捕获路线段子级中的错误（不是同一级别的布局） * **`global-error.tsx`** — 捕获根布局错误；必须包含 `` 和 `` * **`not-found.tsx`** — 当调用 `notFound()` 时显示 * **生产** — 仅将“摘要”（哈希）发送到客户端，而不是错误消息 * **`reset()`** — 重新渲染片段，无需重新加载整页请参阅[示例：错误]()。 ## 身份验证（Auth.js v5） * 单个 `auth()` 函数替换了 `getServerSession`、`getSession`、`useSession` * JWT 策略——无需数据库适配器 * 供应商自动推断的`AUTH_`前缀环境变量 * 通过“authorized”回调保护“proxy.ts”中的路由 * **始终单独验证服务器操作中的身份验证** - 不要仅依赖代理请参阅[示例：auth]()。 ## 安全 * 通过 `next.config.ts` 中的 `headers()` 设置 CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy * `proxy.ts` 中基于 Nonce 的 CSP 用于严格模式（禁用静态渲染） * `NEXT_PUBLIC_` 值在构建时被冻结 — 使用 API 路由来获取运行时可配置的公共值 * `.gitignore` 中的所有 `.env*.local` 文件请参阅[示例：安全性]()。 ## 国际化 * `app/[lang]/` 段 + `proxy.ts` 用于区域设置检测/重定向 * 带有“仅服务器”的字典模式（零客户端捆绑） * `generateStaticParams` 用于每个语言环境的静态渲染 * 图书馆：next-intl、next-international、paraglide-next 请参阅[示例：i18n]()。 ## 工具 (v16) 工具|状态 |配置 ---|---|--- **涡轮机组** |默认捆绑器 |选择退出：`--webpack` **反应编译器** |稳定，选择加入 | next.config.ts 中的 `reactCompiler: true` **代理.ts** |取代 middleware.ts | Node.js 运行时（不是 Edge） React Compiler 自动记忆组件和钩子 - 消除手动“useMemo”、“useCallback”、“React.memo”。 ## 测试层 |工具|用于 ---|---|--- 单元/积分 | Vitest + React 测试库 |客户端组件、同步服务器组件、实用程序端到端|剧作家 |异步服务器组件、全栈流程、水合作用异步服务器组件的剧作家，因为它发出真正的 HTTP 请求 - 单元测试运行程序无法模拟服务器到客户端的管道。 ## 规则 ### 做 * **默认服务器组件** - “使用客户端”仅用于交互 * **并置数据获取** — 在使用它的组件中获取 * **将慢速数据包裹在 Suspense 中** — 流式传输，不阻塞 * **验证所有输入** - 服务器操作和路由处理程序中的 Zod * **检查每个突变中的身份验证** - 操作和路由处理程序中的会话防护 * **使用`notFound()`** — 当数据库查找返回 null 时 * **为每个并行路由槽提供`default.tsx`** * **等待所有动态 API** — params、searchParams、cookies()、headers() * **将错误作为值返回** - 来自服务器操作，不要抛出预期的失败 * **设置安全标头** - 生产中的 CSP、X-Frame-Options、HSTS ### 不要 * **不要假设 fetch 已缓存** — 自 v15 起未缓存；明确选择加入 * **不要跨服务器/客户端边界传递不可序列化的数据** - 没有函数、类、日期 * **不要在服务器组件中使用钩子** - 没有 useState、useEffect、useRef * **不要在客户端组件中获取** - 提升到服务器组件父级或使用查询库 * **不要跳过错误边界** — 每个路由段的“error.tsx”（“使用客户端”） * **不要将原始输入传递到数据库** — 始终使用 Zod 进行验证 * **不要使用 `useFormState`** — 已弃用；使用“react”中的“useActionState” * **不要使用`middleware.ts`** — 已弃用；重命名为“proxy.ts” * **不要在“使用缓存”内调用 cookies()/headers() ** — 在外部读取，作为参数传递

Nextjs 掌握

包含技能