accelint-nextjs-best-practices

Next.js 最佳实践

面向 Next.js 应用的全面性能优化与最佳实践，专为处理 Next.js 代码的 AI Agent 和大模型设计。

何时启用本技能

当任务涉及以下内容时使用本技能：

编写 Next.js 代码

• 创建服务端组件或客户端组件
• 使用 "use server" 实现 Server Actions
• 编写 API 路由处理程序
• 在 RSC（React 服务端组件）中设置数据获取
• 实现 Suspense 边界
• 使用 Next.js 专属 API（headers()、cookies()、after()）

重构 Next.js 代码

• 优化服务端数据获取
• 减少 RSC 序列化开销
• 将串行操作转换为并行操作
• 重构组件组合以提升性能
• 在服务端组件与客户端组件之间迁移

性能优化

• 消除服务端瀑布式请求
• 缩短 API 路由和 Server Actions 的响应时间
• 最小化 RSC 边界处的数据传输
• 使用 React.cache() 实现请求去重
• 使用 after() 执行非阻塞操作

Next.js 专属问题

• Server Actions 中的身份认证/授权
• RSC 序列化重复问题
• 导入优化（桶文件问题）
• 服务端组件与客户端组件的决策
• 并行数据获取模式

代码审查

• 审查 Next.js 代码中的性能反模式
• 识别 Server Actions 中的安全问题
• 检查服务端/客户端组件边界是否正确
• 确保身份认证模式正确
• 校验 Suspense 边界的位置

何时不应使用本技能

以下情况请勿启用：

• React 专属优化（使用 accelint-react-best-practices 技能）
• 构建配置（webpack、turbopack），除非是 Next.js 专属问题
• 通用 TypeScript/JavaScript 问题（使用 accelint-ts-best-practices 技能）
• 部署/托管配置
• 测试设置（使用 accelint-ts-testing 技能）

示例触发语句

当用户说出类似以下内容时，应启用本技能：

性能问题：

• “这个 Next.js API 路由很慢”
• “我的服务端组件阻塞了整个页面”
• “优化这个 Server Action”
• “这个页面加载数据要等很久”
• “我的数据获取中存在瀑布式请求”

安全问题：

• “给这个 Server Action 加上身份认证”
• “这个 Server Action 需要授权”
• “保护这个 API 路由”
• “在这个 Server Action 中校验输入”

调试问题：

• “为什么我的 RSC props 这么大？”
• “这份数据在 HTML 中重复出现了”
• “开发时我的导入很慢”
• “这应该是服务端组件还是客户端组件？”

代码审查：

• “审查这段 Next.js 代码的性能问题”
• “这个 Server Action 安全吗？”
• “你能优化这段数据获取吗？”
• “检查一下这个组件应该是服务端还是客户端”

重构：

• “把这些数据获取并行化”
• “减小序列化体积”
• “把这个改成使用 Suspense”
• “优化这个桶文件导入”

如何使用

本技能采用渐进式披露结构，以尽量减少上下文占用：

1. 从概览开始（AGENTS.md）

阅读 AGENTS.md 获取所有规则的精简概览及一句话摘要。

2. 按需加载特定规则

当你识别出相关的优化点时，加载对应的参考文件以获取详细的实现指导：

通用模式：

• prevent-waterfall-chains.md (1.1)
• parallelize-independent-operations.md (1.2)
• strategic-suspense-boundaries.md (1.3)

服务端性能：

• server-actions-security.md (2.1)
• avoid-duplicate-serialization.md (2.2)
• minimize-serialization.md (2.3)
• parallel-data-fetching.md (2.4)
• react-cache-deduplication.md (2.5)
• use-after-non-blocking.md (2.6)

其他：

• avoid-barrel-imports.md (3.1)
• server-vs-client-component.md (3.2)

快速参考：

• quick-checklist.md
• compound-patterns.md

自动化脚本：

• scripts/ - 用于检测反模式的辅助脚本

3. 应用模式

每个参考文件包含：

• ❌ 展示反模式的错误示例
• ✅ 展示最优实现的正确示例
• 说明该模式为何重要的解释
• 性能影响指标
• 相关模式与参考

4. 使用报告模板

当此技能被调用于 Next.js 代码审查时，使用标准化的报告格式：

模板： assets/output-report-template.md

该报告格式提供：

• 带影响评估的执行摘要
• 用于排定优先级的严重级别（严重、高、中、低）
• 影响分析（性能、安全性、数据传输、可维护性）
• 分类（Server Actions、RSC 序列化、数据获取、组件架构）
• 链接到 references/ 中详细指导的模式引用
• 用于跟踪所有问题的汇总表

何时使用报告模板：

• 通过 /accelint-nextjs-best-practices <path> 直接调用技能
• 用户要求跨文件 “审查 Next.js 代码” 或 “审计 Next.js 应用”，隐式调用技能

何时不使用报告模板：

• 用户要求 “修复这个 Server Action”（直接实现）
• 用户问 “这段代码有什么问题？”（回答问题）
• 用户请求特定修复（直接应用修复，无需正式报告）

示例

示例 1：优化 Server Action 安全性

任务： “为这个 Server Action 添加身份验证”

方法：

1. 阅读 AGENTS.md 概览
2. 识别问题：Server Action 需要身份验证
3. 加载 server-actions-security.md
4. 应用带验证的身份验证模式

示例 2：消除瀑布流

任务： “这个页面因多次获取而加载缓慢”

方法：

1. 阅读 AGENTS.md 概览
2. 识别问题：串行数据获取
3. 加载 prevent-waterfall-chains.md 和 parallelize-independent-operations.md
4. 立即启动操作并使用 Promise.allSettled()

示例 3：减少序列化

任务： “HTML 响应因用户数据而变得巨大”

方法：

1. 阅读 AGENTS.md 概览
2. 识别问题：RSC 边界处的过度序列化
3. 加载 minimize-serialization.md
4. 仅传递必要字段，在客户端进行转换

Additional Resources

Official Next.js documentation:

• App Router Documentation
• Server Components
• Server Actions
• Authentication Guide
• Performance Optimization