当前位置：首页 > news >正文

Next.js ‘use client‘ 到底加在哪:Server/Client Components 边界与常见报错

news 2026/8/3 10:58:44

Next.js ‘use client’ 到底加在哪:Server/Client Components 边界与常见报错

用 Next.js App Router 写页面,你迟早会撞上这个红屏:You're importing a component that needs useState. It only works in a Client Component but none of its parents are marked with "use client"。或者反过来——加了'use client'后,async组件、直接读数据库的代码全报错。这篇把 Server / Client Components 的边界讲透,让你知道那句'use client'到底该写在哪一行。

默认就是 Server Component

App Router 里,所有组件默认是 Server Component,在服务器上运行,输出 HTML 发给浏览器。它们的特点:

可以直接async/await,直连数据库、读文件、调后端 API。
代码不会打包进客户端 bundle,体积更小、密钥更安全。
不能用useState、useEffect、onClick等任何依赖浏览器的东西。

// app/page.tsx —— 默认 Server Component,不用写任何标记 async function Page() { // 直接 await 取数据,这段代码只在服务器跑 const posts = await db.post.findMany(); return ( <ul> {posts.map((p) => <li key={p.id}>{p.title}</li>)} </ul> ); } export default Page;

什么时候必须加 ‘use client’

一旦组件需要交互性或浏览器 API,就得声明成 Client Component。触发条件基本是这几类:

用useState/useReducer/useEffect等 Hook。
绑定事件:onClick、onChange、onSubmit。
用浏览器 API:window、localStorage、document。
用依赖以上能力的第三方库(很多 UI 库、动画库)。

'use client'写在文件最顶部(在所有 import 之上):

'use client'; // 必须是文件第一行(注释除外) import { useState } from 'react'; export default function Counter() { const [n, setN] = useState(0); return <button onClick={() => setN(n + 1)}>点了 {n} 次</button>; }

关键心智模型:‘use client’ 标记的是「边界」,不是「单个文件」

最大的误区是以为要给每个用 Hook 的组件都加'use client'。实际上,'use client'声明的是一个进入客户端的边界:一旦某个文件标了它,这个文件 import 的所有组件、以及它们的子组件,都自动成为 Client Component,不需要每个都再写一遍。

// app/dashboard/Panel.tsx 'use client'; import Chart from './Chart'; // Chart 即使没写 'use client',也是 Client Component import Filter from './Filter'; // 同理 export default function Panel() { // ... }

所以正确做法不是「到处撒'use client'」,而是把边界尽量往叶子节点推:让需要交互的那一小块是 Client Component,页面的其余部分保持 Server Component。这样打包进浏览器的代码最少。

常见报错一:父组件没标记

报错:useState only works in a Client Component but none of its parents are marked with "use client"。

原因:你在一个 Server Component(或它的子树)里用了useState。修复——给这个用 Hook 的组件文件顶部加'use client'。注意是加在用 Hook 的那个组件,不是无脑加到page.tsx。

常见报错二:Client Component 里写了 async

报错:async/await is not yet supported in Client Components。

Client Component不能是async函数,也不能直接await取数据。数据要么在 Server Component 里取好当 props 传进来,要么在 Client Component 里用useEffect+ fetch(或 React Query 之类)。

// ✅ Server Component 取数据,传给 Client Component async function Page() { const user = await getUser(); // 服务器取 return <Profile user={user} />; // 传 props } // Profile.tsx 'use client'; export default function Profile({ user }) { const [editing, setEditing] = useState(false); // 交互在这层 // ... }

常见报错三:传了函数给 Client Component

Server Component 可以给 Client Component 传 props,但props 必须是可序列化的(能 JSON 化):字符串、数字、数组、对象都行。函数、类实例、Date 之外的复杂对象不行:

// ❌ 报错:Functions cannot be passed directly to Client Components async function Page() { const onSave = () => { /* ... */ }; // 这是普通函数,不能传 return <Editor onSave={onSave} />; }

例外:用'use server'标记的Server Action可以作为 prop 传给 Client Component(框架会把它序列化成一个可调用的引用)。普通闭包函数则不行。

一个实用组合:Server 壳 + Client 岛

理想的页面结构是——外层 Server Component 负责取数据和布局,把交互塞进一个个 Client「岛屿」:

// app/post/[id]/page.tsx —— Server,取数据 async function PostPage({ params }) { const post = await db.post.find(params.id); return ( <article> <h1>{post.title}</h1> <p>{post.body}</p> <LikeButton postId={post.id} initial={post.likes} /> {/* Client 岛 */} </article> ); } // LikeButton.tsx —— Client,只有这一小块进浏览器 bundle ('use client'); export default function LikeButton({ postId, initial }) { const [likes, setLikes] = useState(initial); return <button onClick={() => setLikes(likes + 1)}>👍 {likes}</button>; }

标题、正文这些静态内容留在服务器渲染,只有点赞按钮的 JS 被下载到浏览器。

小结

App Router 里默认是 Server Component,能async、直连数据库、不进客户端 bundle。
用到useState/事件/浏览器 API 时才加'use client',写在文件第一行。
'use client'标记的是边界:被它 import 的子树自动都是 Client,不用逐个写;把边界往叶子推,bundle 最小。
三大报错:父组件没标记(给用 Hook 的文件加)、Client 里写async(改成 Server 取数据传 props)、传了普通函数(props 必须可序列化,函数只有 Server Action 例外)。
一句话记忆点:服务器当外壳、客户端当孤岛——'use client'越靠近叶子,打进浏览器的代码越少。