nextjs-app-router

用于 Next.js App Router 模式开发，包含 RSC、Server Actions 和路由最佳实践。来源：skills.sh 10.2K installs。

仓库: seaworld008/Commonly-used-high-value-skills
最近来源活动: 2026年6月29日 03:04
检测到的 SKILL.md 语言: 中文
星标: 64
分支: 10

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

name	nextjs-app-router
description	用于 Next.js App Router 模式开发，包含 RSC、Server Actions 和路由最佳实践。来源：skills.sh 10.2K installs。
zh_description	用于 Next.js App Router 项目开发、路由设计和服务端渲染实践。
version	1.0.0
author	seaworld008
source	skills.sh
source_url	https://skills.sh/wshobson/agents/nextjs-app-router-patterns
license	MIT
tags	["app", "development", "nextjs", "router"]
created_at	2026-03-27
updated_at	2026-03-27
quality	4
complexity	intermediate

Next.js App Router

触发条件

构建现代 Web 应用，需要高性能的 React Server Components (RSC) 渲染架构时。
想要摆脱传统 API 路由模式，利用 Server Actions 直接在 UI 组件中处理表单提交和数据库变更时。
实现复杂的多级路由嵌套、并行路由 (Parallel Routes) 或拦截路由 (Intercepting Routes) 时。
需要利用 Next.js 14+ 的 Metadata API 优化 SEO 和动态社交卡片预览时。
追求极致的加载体验，利用 Streaming、Suspense 和局部加载 (Loading UI) 减少用户等待感时。
在页面级别细粒度控制缓存（Static vs Dynamic）、中间件 (Middleware) 和边缘运行时 (Edge Runtime) 时。

核心能力

1. App Router vs Pages Router 对比

文件系统: app/ 目录下默认所有组件为 Server Components，而 pages/ 默认为 Client Components。
渲染模型: App Router 支持更细粒度的部分渲染（Partial Rendering），而 Pages Router 更多依赖于全页面的 SSR/SSG。
布局流: App Router 通过 layout.tsx 实现跨页面状态保持和 UI 共享，避免不必要的重新渲染。

2. React Server Components (RSC) 最佳实践

数据获取: 在 Server Components 中直接使用 async/await 调用数据库（如 Prisma, Drizzle）或第三方 API，无需外部数据获取 Hook（如 SWR/React Query）。
组件边界: 明确区分 Client Component ("use client") 和 Server Component。尽可能将状态、事件处理器和浏览器 API（如 useEffect, window）封装在小的 Client Component 中，保持大块 UI 为 Server Component 以减少 JS Bundle 体积。

3. Server Actions (数据变更)

表单处理: 使用 action 属性绑定 Server Action，结合 useFormStatus 和 useFormState 处理 Loading 状态和验证反馈。
安全性: 默认具备 CSRF 防护。在 Action 内部执行身份验证 (auth()) 和权限校验。
数据更新: 完成操作后通过 revalidatePath("/") 或 revalidateTag("collection") 触发局部数据缓存刷新。

4. 路由进阶 (Advanced Routing)

Parallel Routes: 使用 @folder 语法在同一布局中同时显示多个独立页面（如仪表盘中同时展示统计表和通知列表）。
Intercepting Routes: 使用 (..) 语法在当前上下文拦截路由（如点击图片在 Modal 中预览，但刷新页面则直接导航至详情页）。
动态路由: 熟练使用 [id]、[[...slug]] (Catch-all) 进行动态路径匹配。

5. 流式传输与 Suspense (Streaming & Suspense)

Loading UI: 在目录中创建 loading.tsx 实现即时的骨架屏反馈。
部分流式: 使用 <Suspense> 包裹耗时的数据拉取组件，允许页面的非阻塞加载，优先显示已就绪的静态内容。

# 启动本地开发服务 (带热更新)
pnpm dev

# 构建生产产物并分析体积 (Next.js Bundle Analyzer)
ANALYZE=true pnpm build

# 快速检查当前路由配置
find app/ -name "page.tsx" -o -name "route.ts" | sort

# 检查 Next.js 版本并升级
pnpm outdated next
pnpm add next@latest react@latest react-dom@latest

// app/users/[id]/page.tsx
import { db } from "@/lib/db";
import { Suspense } from "react";
import UserSkeleton from "@/components/UserSkeleton";

async function UserProfile({ id }: { id: string }) {
  const user = await db.user.findUnique({ where: { id } });
  if (!user) return <div>User not found</div>;
  return <h1>{user.name}</h1>;
}

export default function Page({ params }: { params: { id: string } }) {
  return (
    <main>
      <Suspense fallback={<UserSkeleton />}>
        <UserProfile id={params.id} />
      </Suspense>
    </main>
  );
}

// actions/user-actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function updateUsername(formData: FormData) {
  const name = formData.get("username") as string;
  // 1. 权限校验 (例如使用 next-auth)
  // 2. 数据库更新 (例如 Prisma)
  await db.user.update({ data: { name } });
  
  // 3. 刷新缓存并重定向
  revalidatePath("/profile");
}

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('next-auth.session-token');

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*'],
};