# Next.js 框架指南 > **框架**：Next.js 14+（应用程序路由器） **语言**：TypeScript/JavaScript **用例**：全栈 Web 应用程序、SSR/SSG、电子商务、博客、仪表板 ## 概述 Next.js 是一个 React 框架，在单个代码库中提供服务器端渲染、静态站点生成、API 路由和全栈开发。版本 14+ 使用 App Router 作为默认设置，基于 React Server 组件构建。 ## 项目设置 # 创建新的 Next.js 应用程序 npx create-next-app@latest my-app --typescript --tailwind --eslint --app cd 我的应用程序 npm 运行开发 ### 推荐的项目结构我的应用程序/ ├── 应用程序/ │ ├── (auth)/ # 路由组（无 URL 段） │ │ ├── 登录/page.tsx │ │ └── 寄存器/page.tsx │ ├── 仪表盘/ │ │ ├── page.tsx # /dashboard │ │ ├── loading.tsx # 加载 UI │ │ ├── error.tsx # 错误边界 │ │ └──layout.tsx # 仪表板布局 │ ├── API/ │ │ └── users/route.ts # API 路由处理程序 │ ├── 全局变量.css │ ├──layout.tsx # 根布局（必填） │ └── page.tsx # 主页 (/) ├── 组件/ │ ├── ui/ # 可复用的UI组件 │ └── features/ # 特定功能组件 ├── 库/ │ ├── db.ts # 数据库客户端 │ └── utils.ts # 实用函数 ├── hooks/ # 自定义 React 钩子 ├── types/ # TypeScript 类型定义 ├── public/ # 静态资产 ├── middleware.ts # 边缘中间件 ├── next.config.js ├── tailwind.config.ts └── package.json ## 路由（应用程序路由器） ### 基于文件的路由约定文件 |目的 ---|--- `page.tsx` |路线 UI（使路段可公开访问） `layout.tsx` |共享布局（包裹子项，保留） `loading.tsx` |加载 UI（悬念边界） `error.tsx` |错误边界（必须是“使用客户端”） `未找到.tsx` | 404 该段的用户界面 `route.ts` | API 路由处理程序（GET、POST 等） `模板.tsx` |类似于布局，但重新安装在导航上 `默认.tsx` |并行路线的后备 ### 路线模式应用程序/ ├── page.tsx # / ├── about/page.tsx # /about ├── 博客/ │ ├── page.tsx # /blog │ └── [slug]/page.tsx # /blog/:slug (动态) ├── 店铺/ │ └── [...类别]/page.tsx # /shop/a/b/c (包罗万象) ├── (营销)/ # 路由组(无URL影响) │ ├── 定价/page.tsx # /pricing │ └── features/page.tsx # /features └── @modal/ # 并行路线（命名槽） └── 登录/page.tsx ### 带参数的页面组件 // 应用程序/博客/[slug]/page.tsx 接口 PageProps { 参数：{ slug：字符串}； searchParams: { [键: 字符串]: 字符串 |字符串[] |不明确的 }; } 导出默认函数 BlogPost({ params, searchParams }: PageProps) { 返回

帖子：{params.slug}

; } 导出异步函数generateMetadata({ params }: PageProps): Promise { const post =等待 getPost(params.slug); return { 标题：post.title，描述：post.excerpt }; } ### 布局 // app/layout.tsx -- 根布局（必需，包装整个应用程序）从'next/font/google'导入{Inter}； const inter = Inter({ 子集: ['latin'] }); 导出常量元数据：元数据 = { 标题：{ 默认：'我的应用程序'，模板：'%s |我的应用程序'}, 描述：“我的应用程序”， }; 导出默认函数 RootLayout({ Children }: { Children: React.ReactNode }) { 返回（ {children} ）； } 嵌套布局会自动组合。仪表板布局包含所有 `/dashboard/*` 路由： // 应用程序/仪表板/layout.tsx 导出默认函数 DashboardLayout({ Children }: { Children: React.ReactNode }) { 返回（

<侧边栏/>

{子项}

）； } ## 服务器组件与客户端组件 ### 决策规则需要|元件类型 ---|--- 获取数据，访问后端资源 |服务器（默认）静态渲染、SEO 内容 |服务器使用钩子（useState、useEffect 等）|客户浏览器 API（窗口、localStorage）|客户事件处理程序（onClick、onChange）|客户仅限第三方客户端的库 |客户 ### 服务器组件（默认） `app/` 目录中的所有组件默认都是服务器组件。它们仅在服务器上运行，可以直接访问数据库、文件系统和机密。 // app/users/page.tsx -- 服务器组件（无需指令）从'@/lib/db'导入{db}；导出默认异步函数 UsersPage() { const users = wait db.user.findMany(); 返回（

{user.name}

）； } ### 客户端组件在文件顶部添加“使用客户端”。将该指令推到树中尽可能低的位置。 // 组件/Counter.tsx '使用客户端'；从'react'导入{useState}；导出函数 Counter() { const [count, setCount] = useState(0); return ; } ### 组合模式在服务器组件中获取数据，作为 props 传递给客户端组件： // app/dashboard/page.tsx（服务器组件）从'@/components/ClientSidebar'导入{ClientSidebar}；从'@/lib/db'导入{db}；导出默认异步函数 Dashboard() { const stats =等待db.stats.get(); 返回（

）； } ## 数据获取 ### 使用缓存获取服务器组件异步函数 getProducts() { const res = 等待 fetch('https://api.example.com/products', { next: { revalidate: 3600 }, // ISR: 每小时重新验证 }); if (!res.ok) throw new Error('获取产品失败'); 返回 res.json(); } ### 获取缓存选项选项 |行为 ---|--- `{ 缓存：'强制缓存' }` |静态（GET 的默认值） `{ 缓存：'无存储' }` |动态（无缓存） `{ 下一个：{ 重新验证：N } }` | ISR（每 N 秒重新验证一次） `{ 下一个：{ 标签：['帖子'] } }` |基于标签的重新验证 ### 并行抓取始终与“Promise.all”并行获取独立数据：导出默认异步函数 Dashboard({ params }: { params: { id: string } }) { const [用户，订单] =等待 Promise.all([ getUser(params.id), getOrders(params.id), ]); 返回

; } ### 充满悬念的直播从'react'导入{Suspense}；导出默认函数 Dashboard() { 返回（

<欢迎留言/> }> <统计数据/> }> <最近订单/>

）； } ## 服务器操作使用“使用服务器”定义突变。它们在服务器上运行，可以从表单或客户端代码调用。 // 应用程序/actions.ts '使用服务器'；从'next/cache'导入{revalidatePath}；从“下一步/导航”导入{重定向}；从 'zod' 导入 { z }； const createPostSchema = z.object({ 标题: z.string().min(1), 内容：z.string().min(10), }); 导出异步函数 createPost(formData: FormData) { const 已验证 = createPostSchema.parse({ 标题：formData.get('标题'), 内容：formData.get('内容'), }); 等待 db.post.create({ 数据: 已验证 }); revalidatePath('/posts'); 重定向（`/帖子`）； } 在表单中使用（基本提交不需要客户端 JavaScript）：导出默认函数 NewPost() { 返回（ <表单操作={createPost}> <输入名称=“标题”必需/>

<button type="submit">创建</button>
        </形式>
      ）；
    }

## API 路由处理程序
    
    
    // 应用程序/api/users/route.ts
    从 'next/server' 导入 { NextRequest, NextResponse };
    从 'zod' 导入 { z }；
    
    const userSchema = z.object({
      名称：z.string().min(2),
      电子邮件：z.string().email(),
    });
    
    导出异步函数 GET(请求: NextRequest) {
      const page = parseInt(request.nextUrl.searchParams.get('page') || '1');
      const users = wait db.user.findMany({ 跳过: (页 - 1) * 10, take: 10 });
      返回 NextResponse.json(用户);
    }
    
    导出异步函数 POST(request: NextRequest) {
      尝试{
        const body =等待request.json();
        const 已验证 = userSchema.parse(body);
        const user = wait db.user.create({ 数据: 已验证});
        返回 NextResponse.json(用户, { 状态: 201 });
      } 捕获（错误）{
        if (z.ZodError 错误实例) {
          返回 NextResponse.json({ 错误: error.errors }, { 状态: 400 });
        }
        return NextResponse.json({ error: '内部服务器错误' }, { status: 500 });
      }
    }

## 中间件

在每个匹配的请求之前在边缘运行。用于身份验证检查、重定向、标头。
    
    
    // middleware.ts（项目根目录）
    从'next/server'导入{NextResponse}；
    从 'next/server' 导入类型 { NextRequest }；
    
    导出函数中间件（请求：NextRequest）{
      const token = request.cookies.get('session')?.value;
      const isProtected = request.nextUrl.pathname.startsWith('/dashboard');
    
      if (isProtected && !token) {
        return NextResponse.redirect(new URL('/login', request.url));
      }
    
      返回 NextResponse.next();
    }
    
    导出常量配置= {
      匹配器：['/dashboard/:path*', '/api/:path*'],
    };

## 错误处理

### 错误边界 (`error.tsx`)
    
    
    // 应用程序/仪表板/error.tsx
    '使用客户端'；
    
    导出默认函数 Error({ error, reset }: { error: Error; reset: () => void }) {
      返回（
        <div>
          <h2>出了点问题</h2>
          <button onClick={reset}>重试</button>
        </div>
      ）；
    }

### 未找到
    
    
    // 应用程序/not-found.tsx
    从“下一个/链接”导入链接；
    
    导出默认函数 NotFound() {
      返回（
        <div>
          <h2>未找到</h2>
          <Link href="/">返回首页</Link>
        </div>
      ）；
    }

以编程方式触发：`import { notFound } from 'next/navigation';未找到（）；`

## 配置
    
    
    // next.config.js
    /** @type {import('next').NextConfig} */
    常量 nextConfig = {
      图片：{
        RemotePatterns: [{ 协议: 'https', 主机名: '**.example.com' }],
      },
      异步重定向() {
        return [{ 源：'/old'，目的地：'/new'，永久：true }];
      },
      异步标头() {
        返回[{
          来源：'/api/:路径*'，
          headers: [{ key: 'Access-Control-Allow-Origin', value: '*' }],
        }];
      },
    };
    module.exports = nextConfig;

## 护栏

* 默认使用服务器组件；仅在需要时添加“使用客户端”
  * 将“use client”推到组件树中尽可能低的位置
  * 将数据获取与需要它的组件放在一起
  * 使用`Promise.all`进行独立并行获取
  * 为每个路线段实现 `loading.tsx` 和 `error.tsx`
  * 使用服务器操作进行突变（而不是用于表单提交的 API 路由）
  * 使用服务器操作和 API 路由中的模式验证器 (Zod) 验证所有输入
  * 对图像使用“next/image”，对字体使用“next/font”（性能）
  * 在每个页面上设置适当的元数据以进行 SEO
  * 使用 Suspense 边界来传输慢速数据
  * 切勿在客户端组件中导入仅服务器模块
  * 切勿在客户端组件中暴露秘密或数据库访问权限

## 命令参考
    
    
    npm run dev # 开发服务器 (http://localhost:3000)
    npm run build # 生产版本
    npm run start # 启动生产服务器
    npm run lint # ESLint 检查
    npx tsc --noEmit # TypeScript 验证
    npm test # 运行测试 (Vitest/Jest)

## 高级主题

详细的代码示例、高级模式、测试策略、性能优化、缓存策略以及 ISR/SSG/SSR 详细信息，请参阅：

* [references/patterns.md](<https://github.com/ar4mirez/samuel/blob/HEAD/.claude/skills/nextjs/references/patterns.md>) \-- 身份验证、高级服务器操作、测试、性能、缓存、渲染策略、部署

## 外部参考

* [Next.js 文档](<https://nextjs.org/docs>)
  * [Next.js 应用路由器](<https://nextjs.org/docs/app>)
  * [NextAuth.js / Auth.js](<https://authjs.dev/>)
  * [Vercel 部署](<https://vercel.com/docs>)
  * [React 服务器组件](<https://react.dev/reference/rsc/server-components>)</article></body></html>

下一个js

包含技能