nextjs-best-practices

nextjs-best-practices 快速入门

让 AI 写 Next.js 代码时,直接生成 Vercel 官方推荐写法。

这是什么?解决什么问题?

Next.js 是当前最流行的 React 框架,但它本身更新非常快。App Router、Server Components、Streaming、Partial Prerendering、PPR 这些新概念每隔几个月就变一次。普通开发者写出来的代码,可能一两年后就被官方标记为”反模式”。 nextjs-best-practices 是一个汇总了 Vercel 官方推荐写法的 Skill。它把官方文档、Next.js Conf 演讲、内部技术博客里的最佳实践浓缩成 AI 能直接调用的规则集。当 AI 给你的 Next.js 项目加新功能时,它会:

• 默认使用 App Router(不是过时的 Pages Router)
• 默认使用 Server Components,只在需要交互时才加 “use client”
• 帮你写好 loading.tsx、error.tsx、not-found.tsx 这些约定文件
• 自动启用 Streaming SSR、Suspense 边界、并行数据获取
• 提示你用 <Image>、<Link>、<Font> 这些内置优化组件 这个 Skill 适合写 Next.js 全栈应用、做 SSR/SEO 优化、追求 Core Web Vitals 满分的开发者。

准备工作

• Node.js 18+ 和 npm/pnpm
• 一个支持 Agent Skill 的客户端(Claude Code、Cursor 等)
• 现有的 Next.js 项目,或者新建一个
• 30 分钟学习时间

3 步快速上手

第 1 步:克隆 awesome-agent-skills 仓库

git clone https://github.com/JackyST0/awesome-agent-skills.git
cd awesome-agent-skills
ls skills/nextjs-best-practices/

你会看到 Skill 定义文件、参考文档、示例项目。

第 2 步:在 AI 客户端里加载 Skill

# Claude Code 方式
claude --skill nextjs-best-practices
# Cursor 方式(在 .cursorrules 里加)
echo "Use the nextjs-best-practices skill from this repo" > .cursorrules

第 3 步:让 AI 帮你改造一个页面

准备一个旧的 Pages Router 页面(或新建一个 App Router 项目),让 AI 改造:

“把这个 Pages Router 的产品列表页改成 App Router,用 Server Components 拉数据,加 loading.tsx,优化 SEO。”

AI 会输出:

// app/products/page.tsx (Server Component, 默认)

import { Suspense } from 'react'

import { ProductList } from './product-list'

export default async function ProductsPage() {

return (

<main>

<h1>产品列表</h1>

<Suspense fallback={<ProductsSkeleton />}>

<ProductList />

</Suspense>

</main>

)

}

并自动配套生成 loading.tsx、error.tsx、product-list.tsx(客户端组件)。

常见踩坑

1. Server Component 里用 onClick:Server Component 不能有交互。如果 AI 给你写的组件带 onClick,那就是错误,必须把交互部分抽成 “use client” 组件。

2. 把 fetch 写在 Client Component:Next.js 的 fetch 缓存只在 Server Component 生效。把 fetch 写到 “use client” 里,缓存就失效了。

3. 过度使用 “use client”:很多新手图省事,所有组件都标 client,结果整个应用都是客户端渲染,失去 SSR 优势。Skill 会强制约束。

4. 忘了 metadata 导出:SEO 关键。每个 page.tsx 都应该有 export const metadata: Metadata = { title: '...', description: '...' }。

5. 动态路由参数忘了 await:params 在 Next.js 15+ 是 Promise,必须 const { id } = await params,不是直接解构。Skill 会自动按新规范写。

6. 图片优化不彻底:用了 <img> 而不是 <Image>,没有 width/height,导致 CLS 高。

初级用法

• 新项目脚手架:让 AI 用 Skill 直接生成 npx create-next-app 之后的最佳实践目录结构。

• 迁移 Pages Router 到 App Router:把老项目逐页迁移,Skill 会处理 90% 的样板代码。

• 添加 Loading/Error 边界:让 AI 帮你补齐 loading.tsx、error.tsx 这些约定文件,提升用户体验。

高级玩法

• Server Actions:Next.js 14+ 的 Server Actions 用法,Skill 会自动生成带 type-safe 表单处理的代码。

• Parallel Routes 和 Intercepting Routes:高级路由模式,Skill 会给出官方推荐实现。

• Partial Prerendering (PPR):Next.js 15 实验性功能,静态部分立即渲染,动态部分流式加载,Skill 能帮你配置 next.config.js。

小技巧

• 写完页面后,问 AI “用 nextjs-best-practices 帮我 review 一遍这个文件”,它会标出所有反模式。

• 配合 Vercel 部署,真正的端到端最佳实践就闭环了。

• 用 next build 时如果报警告,大部分都是 Skill 警告过的内容,跟着警告改就行。

• Server Component 之间传函数是有限制的(必须是 Server Action),别硬塞闭包。

• 部署到 Vercel 后打开 Vercel Analytics,可以看到 Skill 推荐的优化点对应的真实性能提升。