NextJS技能使用说明

设置

首次使用时，请阅读setup.md以了解项目集成。

使用场景

用户需要 Next.js 专业知识时——如路由、数据获取、缓存、身份验证或部署。代理负责处理应用路由器模式、服务器/客户端边界以及生产环境优化。

架构

项目模式存储在~/nextjs/目录下。请参阅memory-template.md以进行设置。

~/nextjs/
├── memory.md          # Project conventions, patterns
└── projects/          # Per-project learnings

快速参考

核心规则

1. 默认使用服务端组件

在应用路由器中，所有内容都是服务端组件。仅当需要使用 useState、useEffect、事件处理程序或浏览器 API 时，才添加'use client'。服务端组件不能导入到客户端组件中——应通过子组件形式传递。

2. 在服务端获取数据

在服务端组件中获取数据，而非使用 useEffect。对于并行请求，使用Promise.all。具体模式请参阅data-fetching.md。

3. 有意识地缓存

fetch默认具有缓存——对于动态数据，请使用cache: 'no-store'。设置revalidate针对ISR，请参考caching.md获取相关策略。

4. 用于数据变更的服务器操作

在表单提交和数据变更时使用'use server'函数。支持渐进式增强——无需JavaScript即可工作。详见data-fetching.md。

5. 环境安全性

NEXT_PUBLIC_前缀的变量会暴露给客户端包。服务器组件可访问所有环境变量。请使用.env.local存储敏感信息。

6. 大数据的流式传输

使用<Suspense>边界逐步流式传输内容。请单独包装加载缓慢的组件。详见data-fetching.md。

7. 中间件层级的身份验证

请在中间件中而非页面内保护路由。中间件运行在Edge环境——仅适用于轻量级身份验证检查。详见auth.md.

服务器端 vs 客户端

决策：从服务器组件开始。仅当需要以下功能时添加'use client'：useState、useEffect、onClick、浏览器 API。

常见陷阱

Next.js 15 变更

• 参数和searchParams现在是Promise— 必须 await
• fetch默认不缓存 — 通过cache: 'force-cache'
• 选择启用使用 React 19 钩子：useActionState、

useFormStatus

相关技能使用clawhub install <slug>

• 安装如果用户确认：
• react— React 基础与模式
• typescript— 类型安全以提升开发体验
• prisma— 用于 Next.js 应用的数据库 ORM
• tailwindcss— 服务器运行时知识

反馈

• 如果有用：clawhub star nextjs
• 保持更新：clawhub 同步