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

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' 越靠近叶子,打进浏览器的代码越少。