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等任何依赖浏览器的东西。
tsx
// 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 之上):
tsx
'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,不需要每个都再写一遍。
tsx
// 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 之类)。
tsx
// ✅ 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 之外的复杂对象不行:
tsx
// ❌ 报错: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「岛屿」:
tsx
// 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'越靠近叶子,打进浏览器的代码越少。