企业官网建设流程全解析

React 服务端组件的客户端边界：use client 指令的正确使用模式

一、RSC 架构中的边界语义：use client不是你想的那样

React Server Components（RSC）引入了一种全新的组件分层模型：服务端组件在服务器上渲染，客户端组件在浏览器中渲染，两者通过明确的边界指令进行划分。use client就是这个边界标记。

但use client的语义经常被误解。很多开发者以为它标记了一个"只在客户端运行"的组件，实际上它标记的是一个"客户端入口点"——即从这个文件开始，整个子树将在客户端渲染。更精确地说，use client声明的是模块的客户端执行环境边界，而不是组件本身的生命周期属性。

以下是一个典型的边界标记：

// app/components/UserProfile.tsx // 'use client' 表示该模块及其导入的所有模块在客户端执行 'use client'; import { useState, useEffect } from 'react'; import { fetchUserData } from '@/lib/api'; // 该模块也会被打包到客户端 import { Avatar } from './Avatar'; // 同样在客户端执行 export function UserProfile({ userId }: { userId: string }) { const [data, setData] = useState<UserData | null>(null); useEffect(() => { fetchUserData(userId) .then(setData) .catch((err) => { console.error('用户数据加载失败:', err); }); }, [userId]); if (!data) return <div>加载中...</div>; return ( <div className="profile-card"> <Avatar src={data.avatarUrl} alt={data.name} /> <h2>{data.name}</h2> </div> ); }

二、边界传染效应：一张图理解模块依赖链

use client最核心的行为特性是"传染性"。当你在一个文件中使用了use client，所有被这个文件直接或间接导入的模块，都会自动被打包到客户端 bundle 中，无论这些模块是否包含交互逻辑。

这个特性会带来一个隐蔽的性能陷阱：一个纯工具函数模块（比如日期格式化库），如果被标记了use client的组件引用，会导致整个工具模块的体积被计入客户端 bundle。在大型项目中，这种传染效应可能导致几百 KB 的不必要传递。

flowchart LR subgraph Server["服务端"] A["page.tsx<br/>（服务端组件）"] end subgraph Boundary["use client 边界"] B["InteractivePanel.tsx<br/>'use client'"] end subgraph Client["客户端 Bundle"] C["Button.tsx<br/>（交互组件）"] D["usePanelState.ts<br/>（状态 hook）"] E["utils/format.ts<br/>（被传染的工具函数）"] F["icons/index.ts<br/>（被传染的图标库）"] end A -->|"import"| B B -->|"直接引用"| C B -->|"直接引用"| D C -->|"间接引用"| E D -->|"间接引用"| F style Boundary fill:#f59e0b,color:#fff style Server fill:#10b981,color:#fff style Client fill:#3b82f6,color:#fff

三、三种常见的错误使用模式

错误一：在不需要交互的地方添加use client

有些开发者会将整个页面目录标记为use client，目的是避免处理 RSC 的限制（例如不能使用useState）。这种做法完全抵消了 RSC 的性能收益。

// 错误示范：整个页面都成了客户端组件 // app/dashboard/page.tsx 'use client'; // 不应该在这里 import { DashboardStats } from './stats'; // 纯展示组件，不需要客户端 import { RecentOrders } from './orders'; // 纯展示组件，不需要客户端 export default function DashboardPage() { // DashboardStats 和 RecentOrders 完全可以使用服务端渲染 return ( <> <DashboardStats /> <RecentOrders /> </> ); }

修复方案：将use client下推到真正需要交互的叶子组件。

// 正确示范：仅在交互组件中使用 'use client' // app/dashboard/page.tsx（服务端组件） import { DashboardStats } from './stats'; // 服务端渲染 import { OrderFilter } from './order-filter'; // 客户端交互组件 export default function DashboardPage() { return ( <> <DashboardStats /> <OrderFilter /> {/* 'use client' 写在这个组件内部 */} </> ); }

错误二：将use client模块导出的常量用于服务端

当服务端组件从use client文件中导入常量时，相关代码会被意外地打入客户端 bundle。

// 错误：constants.ts 被标记为 'use client'， // 虽然常量本身不需要客户端环境 // constants.ts 'use client'; export const MAX_DISPLAY_COUNT = 100; // 服务端页面引用了这个常量 // 导致整个 constants 模块被推入客户端 // page.tsx import { MAX_DISPLAY_COUNT } from './constants'; // 传染发生

错误三：不理解use client模块中依然可以使用服务端渲染的部分

即使是use client组件，其初始 HTML 仍然可以在服务端生成（SSR）。组件中的静态部分不会被重复发送，只有交互逻辑和水合代码进入客户端 bundle。

四、边界治理的工程化实践

在大型项目中，需要建立自动化的边界治理机制。

第一，使用 ESLint 插件eslint-plugin-react-server-components强制执行 RSC 的边界约束。该插件可以检测出服务端组件中对客户端 API 的错误引用。

第二，通过 bundle 分析工具（如@next/bundle-analyzer）定期审查客户端 bundle 的体积变化。当发现某次提交导致客户端 bundle 体积异常增长时，优先排查是否存在use client的传染扩散。

第三，建立组件目录的契约规范。在项目根目录创建components分层结构：

components/ ├── server/ # 服务端组件，禁止使用 use client │ ├── product-card.tsx │ └──>// eslint 自定义规则：检测 server/ 目录下的 'use client' 使用 // eslint-local-rules/no-use-client-in-server-dir.js module.exports = { meta: { type: 'problem', docs: { description: '禁止在 server/ 目录中使用 use client 指令', }, }, create(context) { const filename = context.getFilename(); // 如果是 server/ 目录中的文件，检测是否包含 'use client' if (filename.includes('/server/') || filename.includes('\\server\\')) { return { ExpressionStatement(node) { const source = context.getSourceCode().getText(node); if ( node.directive === 'use client' || source.includes("'use client'") ) { context.report({ node, message: 'server/ 目录下的组件禁止使用 use client 指令。' + '如需添加交互，请将交互逻辑移至 client/ 目录。', }); } }, }; } return {}; }, };

五、总结

use client指令是 RSC 架构中控制渲染边界的关键机制，但它的传染性决定了必须谨慎使用。核心原则有三条：第一，use client应尽可能靠近叶子组件，不要写在上层布局或页面中；第二，纯工具函数模块应避免被use client组件引用，如果必须引用，考虑将工具函数模块拆分为纯逻辑层和客户端适配层；第三，通过 ESLint 规则和 bundle 分析工具建立自动化的边界治理机制。

RSC 的性能收益取决于边界绘制的精确程度。每一处不必要的use client都是一笔持续支付的性能债务。