# Next.js 服务器组件与客户端组件 ## 概述提供有关在 Next.js App Router 中的服务器组件和客户端组件之间进行选择的全面指南，包括 cookie/标头访问、searchParams 处理、路径名路由以及 React 的“使用”API 进行 Promise 解包。 ## TypeScript：永远不要使用“任何”类型 **关键规则：** 此代码库启用了“@typescript-eslint/no-explicit-any”。使用“any”将导致构建失败。 **❌ 错误：** 函数handleSubmit(e: 任意) { ... } 常量数据：any[] = []； **✅ 正确：** 函数handleSubmit(e: React.FormEvent) { ... } 常量数据：字符串[] = []； ### 常见的 Next.js 类型模式 // 页面道具函数页面({ params }: { params: { slug: string } }) { ... } 函数页面({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... } // 表单事件 const handleSubmit = (e: React.FormEvent) => { ... } const handleChange = (e: React.ChangeEvent) => { ... } // 服务器动作异步函数 myAction(formData: FormData) { ... } ## 何时使用此技能在以下情况下使用此技能： * 决定使用服务器组件还是客户端组件 * 访问 cookie、标头或其他服务器端数据 * 使用 searchParams 或路由参数 * 需要路径名或路由信息 * 使用 React“use”API 解开 Promise * 调试“使用客户端”边界问题 * 优化组件渲染策略 ## 核心决策：服务器与客户端组件 ### 默认：服务器组件 **默认情况下，App Router 中的所有组件都是服务器组件。** 无需指令。 // 应用程序/组件/ProductList.tsx // 这是一个服务器组件（默认）导出默认异步函数 ProductList() { const products = wait fetch('https://api.example.com/products'); const data =等待products.json(); 返回（

{product.name}

）； } **何时使用服务器组件：** * 从API或数据库获取数据 * 访问后端资源（环境变量、文件系统） * 处理敏感信息（API密钥、令牌） * 减少客户端 JavaScript 捆绑 * SEO 关键内容渲染 * 静态或不经常变化的内容 **好处：** * 默认情况下客户端 JavaScript 为零 * 直接数据库/API访问 * 安全处理秘密 * 自动代码分割 * 更好的初始页面加载性能 * 减少捆绑尺寸 ### 客户端组件：“使用客户端” 在文件顶部添加“use client”指令以使其成为客户端组件。 // 应用程序/组件/Counter.tsx '使用客户端'；从'react'导入{useState}；导出默认函数 Counter() { const [count, setCount] = useState(0); 返回（ <按钮 onClick={() => setCount(count + 1)}> 计数：{计数} ）； } **何时使用客户端组件：** * 需要React钩子（useState、useEffect、useContext等） * 事件处理程序（onClick、onChange、onSubmit 等） * 仅限浏览器的 API（窗口、localStorage、导航器） * 需要浏览器环境的第三方库 * 交互式 UI 元素（模式、下拉菜单、表单） * 实时功能（WebSocket、动画） **客户端组件的要求：** * 文件顶部必须有“use client”指令 * 不能在组件中直接使用async/await * 无法访问仅服务器 API（cookie、标头） * 所有导入的组件都成为客户端组件 ### ⚠️ 关键：服务器组件永远不需要“使用客户端” **服务器组件是默认组件。除非您特别需要客户端功能，否则请勿添加“使用客户端”。** **✅ 正确 - 带导航的服务器组件：** // app/page.tsx - 服务器组件（不需要“使用客户端”！）从“下一个/链接”导入链接；从“下一步/导航”导入{重定向}；导出默认异步函数 Page() { // 服务器组件可以是异步的 const data = 等待 fetchData(); 如果（！数据）{ 重定向（'/登录'）； // 服务器端重定向 } 返回（

转到仪表板

{数据.内容}

）； } **❌ 错误 - 将“使用客户端”添加到服务器组件：** // 应用程序/page.tsx '使用客户端'； // ❌ 错误！不要将其添加到服务器组件中！ export default async function Page() { // ❌ 将失败 - 不允许使用异步客户端组件 const data = 等待 fetchData(); 返回

{data.content}

; } **服务器导航方法（无需“使用客户端”）：** * 来自“next/link”的“”组件 * 来自“next/navigation”的“redirect()”函数 * 服务器操作（参见高级路由技巧） **客户端导航方法（需要“使用客户端”）：** * `useRouter()` 钩子来自 `next/navigation` * `usePathname()` 钩子 * `useSearchParams()` 钩子（也需要 Suspense） ## 服务器组件模式 ### 访问 Cookie 使用“next/headers”读取服务器组件中的cookie： // 应用程序/仪表板/page.tsx 从'next/headers'导入{cookies}；导出默认异步函数 Dashboard() { const cookieStore = 等待 cookies(); const token = cookieStore.get('会话令牌'); 如果（！令牌）{ 重定向（'/登录'）； } const user = wait fetchUser(token.value); return

欢迎，{user.name}

; } **重要说明：** * Next.js 15+ 中必须等待 `cookies()` * Cookie 在服务器组件中是只读的 * 要设置cookie，请使用服务器操作（请参阅高级路由技巧） * Cookie 访问仅在服务器组件中可用 ### 访问标头 // app/api/route.ts 或任何服务器组件从 'next/headers' 导入 { headers }；导出默认异步函数 Page() { const headersList = 等待 headers(); const userAgent = headersList.get('用户代理'); const Referer = headersList.get('referer'); 返回

用户代理：{userAgent}

； } ### 使用搜索参数直接在服务器组件中访问 URL 查询参数： // 应用程序/搜索/page.tsx 导出默认异步函数 SearchPage({ 搜索参数， }：{ searchParams: { q?: 字符串;类别？：字符串}； }) { const 查询 = searchParams.q || ''; const 类别 = searchParams.category || '全部'; const 结果 = 等待 searchProducts(查询, 类别); 返回（

搜索结果：{query}

类别：{类别}

）； } **重要说明：** * `searchParams` 仅在 `page.tsx` 文件中可用 * 在 Next.js 15+ 中，必须等待 `searchParams` * searchParams 在 `layout.tsx` 中不可用 * 如果需要，在客户端组件中使用客户端 `useSearchParams()` 钩子 **⚠️ 严重警告 - Next.js 15+ searchParams：** 在 Next.js 15+ 中提取参数时，必须使用解构来保持“searchParams”标识符与参数提取在同一行中可见。不要使用“params”或“resolved”等中间变量 - 这是一种反模式，会破坏代码可读性和测试模式。 **异步搜索参数（Next.js 15+）：** // app/search/page.tsx (Next.js 15+) 导出默认异步函数 SearchPage({ 搜索参数， }：{ searchParams: Promise<{ q?: string }>; }) { // 最佳实践：内联访问将 searchParams 和参数放在一行上 const q = (等待 searchParams).q || ''; return

搜索：{q}

; } **关键模式要求：** 从“searchParams”中提取参数时，**始终使用内联访问**将“searchParams”和参数名称保留在同一行： // ✅ 正确：内联访问（必需模式） const name = (等待 searchParams).name || ''; // ✅ 同样正确：多个参数 const 类别 = (等待 searchParams).category || '全部'; const sort = (等待 searchParams).sort || '升序'; // ❌ 错误：使用中间变量将 searchParams 与参数分开 const params = 等待 searchParams； // 不要这样做 const 名称 = params.name; // searchParams 在这里不可见 // ❌ 错误：解构（searchParams 和名称在同一行，但缺少第二个“名称”） const { name } = 等待 searchParams; // 不优选 **为什么内联访问：** * 保持“searchParams”标识符与参数提取在同一行可见 * 明确URL参数和变量之间的关系 * 满足代码审查和测试模式，检查 searchParams 的使用是否正确 ### 使用路径名和路由信息 **在服务器组件 (page.tsx) 中：** // 应用程序/博客/[slug]/page.tsx 导出默认异步函数 BlogPost({ 参数， }：{ 参数：{ slug：字符串}； }) { // params 包含路由参数 const post =等待 getPost(params.slug); 返回

{post.title}

; } **异步参数（Next.js 15+）：** // app/blog/[slug]/page.tsx (Next.js 15+) 导出默认异步函数 BlogPost({ 参数， }：{ 参数： Promise<{ slug: string }>; }) { const { slug } = 等待参数； const post = 等待 getPost(slug); 返回

{post.title}

; } **在客户端组件中：** 使用“next/navigation”中的钩子： // 应用程序/组件/Breadcrumbs.tsx '使用客户端'；从 'next/navigation' 导入 { usePathname, useParams, useSearchParams }; 导出默认函数 Breadcrumbs() { const 路径名 = usePathname(); // 当前路径：/blog/hello-world const params = useParams(); // 路由参数: { slug: 'hello-world' } const searchParams = useSearchParams(); // 查询参数返回（ <导航> 当前路径：{路径名} Slug：{params.slug} 搜索：{searchParams.get('q')} ）； } ### ⚠️ 关键：useSearchParams 始终需要悬念 **当使用`useSearchParams()`钩子时，你必须：** 1. 在文件顶部添加 `'use client'` 指令 2. 将组件包裹在 Suspense 边界中这是 **Next.js 要求** \- 未能同时执行这两项操作将导致错误。 **✅ 正确模式：** // app/page.tsx 或任何父组件从'react'导入{Suspense}；从 './SearchComponent' 导入 SearchComponent；导出默认函数 Page() { 返回（加载中...}> <搜索组件/> ）； } // 应用程序/SearchComponent.tsx '使用客户端'；从 'next/navigation' 导入 { useSearchParams }；导出默认函数SearchComponent() { const searchParams = useSearchParams(); const query = searchParams.get('q'); return

搜索查询：{query}

; } **❌ 错误 - 缺少“使用客户端”：** // 这将失败 - useSearchParams 需要“使用客户端” 从 'next/navigation' 导入 { useSearchParams }；导出默认函数SearchComponent() { const searchParams = useSearchParams(); // 错误！返回

{searchParams.get('q')}

; } **❌ 错误 - 缺少悬念包装：** // 这会导致问题 - useSearchParams 需要 Suspense 导出默认函数 Page() { 返回 ; // 缺少悬念包装！ } ## React“使用”API 进行 Promise 解包 React `use` API 允许读取服务器和客户端组件中的承诺和上下文。 ### 将“use”与 Promise 结合使用 // 应用程序/组件/UserProfile.tsx '使用客户端'；从“反应”导入{使用}； // 重要提示：使用特定类型、泛型类型或“未知”——切勿使用“任何” // 选项 1：特定类型（类型已知时最好）导出默认函数 UserProfile({ 用户承诺 }：{ userPromise: Promise<{ 名称: 字符串;电子邮件：字符串}> }) { // 解开承诺 const 用户 = use(userPromise); 返回

{用户名}

; } // 选项 2：通用类型（用于可重用组件）导出函数 GenericDataDisplay({ 数据 }：{ 数据：承诺 }) { const 结果 = 使用（数据）；返回

{JSON.stringify(结果)}

; } // 选项 3：未知类型（当类型确实未知时）导出函数UnknownDataDisplay({ 数据 }：{ 数据：承诺<未知> }) { const 结果 = 使用（数据）；返回

{JSON.stringify(结果)}

; } **服务器组件传递承诺：** // 应用程序/个人资料/page.tsx 从 './components/UserProfile' 导入 UserProfile；导出默认函数 ProfilePage() { // 创建 Promise 但不等待 const userPromise = fetchUser(); 返回（加载中...}> ）； } ### “使用”API 的好处 * 启用并行数据获取 * 适用于悬念边界 * 允许服务器组件将承诺传递给客户端组件 * 比螺旋桨钻井异步数据更干净 ### 在上下文中使用“use” '使用客户端'；从“反应”导入{使用}；从'./ThemeContext'导入{ThemeContext}；导出默认函数 ThemedButton() { const 主题 = use(ThemeContext); return ; } ## 常见模式 ### 模式 1：服务器组件获取，客户端组件交互 // app/products/page.tsx（服务器组件）从 './ProductGrid' 导入 ProductGrid；导出默认异步函数 ProductsPage() { const products = 等待 fetchProducts(); // 将数据传递给客户端组件返回 ; } // app/products/ProductGrid.tsx（客户端组件） '使用客户端'；从'react'导入{useState}；导出默认函数 ProductGrid({ 产品 }：{ 产品：产品[] }) { const [filter, setFilter] = useState('全部'); const 过滤 = products.filter(p => 过滤器 === '全部' || p.category === 过滤器）；返回（

Nextjs 服务器客户端组件

包含技能