引言
在 Next.js App Router 项目中，TypeScript 有时会给出一个让人摸不着头脑的报错：TS71007: Prop xxx is not serializable。明明组件写得很正常，props 也不过是常见的回调函数，为什么 Next.js 会认为它"不可序列化"？
这背后其实是 Next.js 对 Server Component 与 Client Component 边界 的处理机制在起作用。一旦对 "use client" 的使用方式出现偏差------尤其是给一个本不需要声明客户端身份的叶子组件单独加了 "use client"，就会让 Next.js 把它误判为「服务端→客户端」的入口边界，从而触发不必要的 props 序列化检查，最终抛出 TS71007。
本文从一个真实的 FloatBar.tsx 报错出发，从读者的视角逐步分析问题、讨论原理、给出修复方案，并整理表格对比与决策流程图，帮助你一次性理清 Next.js 中 "use client" 与该类报错的关系。
目录
- [问题现象：一个典型的 TS71007 报错](#问题现象：一个典型的 TS71007 报错)
- 原因分析：为什么会被误判为入口边界
- [关键原理：
"use client"的向下传播机制](#关键原理："use client" 的向下传播机制) - 修复方案：去掉多余的
"use client" - [表格对比：
"use client"使用场景一览](#表格对比："use client" 使用场景一览) - [决策流程：遇到 TS71007 该怎么排查](#决策流程：遇到 TS71007 该怎么排查)
- 总结
问题现象
在 apps/webgui/New/Theme/src/app/(main)/simulator/topology/widgets/FloatBar.tsx 中，组件顶部单独声明了：
tsx
"use client";
import React from "react";
interface FloatBarProps {
onToggleAllMiniPanels: () => void;
onToggleIpLabel: () => void;
// ...
}其余代码本身没有逻辑问题，但 Next.js 在构建或做类型校验时抛出 TS71007，提示传入 FloatBar 的函数类型 prop（如 onToggleAllMiniPanels、onToggleIpLabel）不可序列化。
对于还不熟悉 Next.js 边界机制的读者来说，第一反应往往是：是不是我的 props 类型写错了？ 但实际上，这是 Next.js 在「服务端组件 → 客户端组件」边界处做的可序列化校验，而不是普通的 React 类型错误。
原因分析
FloatBar.tsx 顶部单独声明了 "use client"。在 Next.js App Router 中，任何带 "use client" 的文件都会被当作 server → client 的入口边界，并对跨边界传入的 props 做「可序列化」校验。
函数类型、类实例、Date、Map 等对象都不在可序列化范围内，因此当父组件向 FloatBar 传入回调函数时，Next.js 会认为这些函数类型 prop 无法从服务端传到客户端，从而报出 TS71007。
但真实情况是：FloatBar 只被 TopologyCanvas.tsx 和 TopologyNewCanvas.tsx 引用，而这两个文件已经各自声明了 "use client" 。也就是说，FloatBar 实际运行在客户端，根本不存在「从服务端跨边界传入函数」这一场景。
关键原理
在 Next.js 的模型里，"use client" 会向下游自动传播：被客户端组件 import 的模块，本身就已经是客户端代码，无需再单独声明。
换句话说：
- 只要
TopologyCanvas.tsx已经是客户端组件； - 它 import 的
FloatBar.tsx就自动属于客户端模块； FloatBar即使不写"use client"，也能使用useTranslation等客户端 hook。
所以给一个纯叶子组件重复加 "use client"，不但没有任何收益，反而会让它被错误地当成独立入口边界，触发没意义的序列化检查。这是本次 TS71007 报错的根本原因。
修复方案
去掉 FloatBar.tsx 顶部的 "use client" 即可：
tsx
import React from "react";
interface FloatBarProps {
onToggleAllMiniPanels: () => void;
onToggleIpLabel: () => void;
}
const FloatBar = ({ onToggleAllMiniPanels, onToggleIpLabel }: FloatBarProps) => {
// 省略具体实现
};
export default FloatBar;修改后，FloatBar 仍是客户端树中的普通模块，通过其父组件 TopologyCanvas / TopologyNewCanvas 的 "use client" 获得客户端身份。useTranslation 等 hook 不受影响，TS71007 报错消失，运行时行为也不会有任何变化。
同类报错的通用处理
如果同类报错也出现在其它「叶子 UI 组件」中，例如 DockBar、HelpTip、DispatchMask 等被客户端组件引用的 widgets，可以按相同方式排查：只保留真正的客户端路由入口（如 TopologyCanvas）上的 "use client" 即可，被这些入口组件引用的叶子组件不需要再声明。
表格对比
下表从多个维度对比「服务端组件」「真正客户端入口」「被客户端 import 的叶子组件」三者的差异：
| 维度 | 服务端组件（默认） | 真正的客户端入口组件 | 被客户端 import 的叶子组件 |
|---|---|---|---|
是否写 "use client" |
不写 | 写 | 不需要写 |
| 运行环境 | Node.js 服务端 | 浏览器客户端 | 浏览器客户端 |
能否使用 hooks（如 useState、useTranslation） |
否 | 能 | 能（随入口传播） |
| 传 props 是否需可序列化 | 不适用 | 跨边界传 props 需可序列化 | 客户端内部传 props 无此限制 |
| 是否触发 TS71007 序列化检查 | 否 | 边界处可能触发 | 写了多余 "use client" 才会触发 |
FloatBar 所属场景 |
--- | TopologyCanvas |
FloatBar |
结论：一旦给「被客户端 import 的叶子组件」重复写
"use client"，它就从"普通客户端模块"被提升为"边界入口"，从而被套上不该有的 props 序列化检查。
决策流程
遇到 Next.js TS71007 串行化相关报错时，可以按照下面的流程图排查：
#mermaid-svg-ElnlAZBpZ3QzPYsu{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ElnlAZBpZ3QzPYsu .error-icon{fill:#552222;}#mermaid-svg-ElnlAZBpZ3QzPYsu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ElnlAZBpZ3QzPYsu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .marker.cross{stroke:#333333;}#mermaid-svg-ElnlAZBpZ3QzPYsu svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ElnlAZBpZ3QzPYsu p{margin:0;}#mermaid-svg-ElnlAZBpZ3QzPYsu .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster-label text{fill:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster-label span{color:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster-label span p{background-color:transparent;}#mermaid-svg-ElnlAZBpZ3QzPYsu .label text,#mermaid-svg-ElnlAZBpZ3QzPYsu span{fill:#333;color:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .node rect,#mermaid-svg-ElnlAZBpZ3QzPYsu .node circle,#mermaid-svg-ElnlAZBpZ3QzPYsu .node ellipse,#mermaid-svg-ElnlAZBpZ3QzPYsu .node polygon,#mermaid-svg-ElnlAZBpZ3QzPYsu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .rough-node .label text,#mermaid-svg-ElnlAZBpZ3QzPYsu .node .label text,#mermaid-svg-ElnlAZBpZ3QzPYsu .image-shape .label,#mermaid-svg-ElnlAZBpZ3QzPYsu .icon-shape .label{text-anchor:middle;}#mermaid-svg-ElnlAZBpZ3QzPYsu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .rough-node .label,#mermaid-svg-ElnlAZBpZ3QzPYsu .node .label,#mermaid-svg-ElnlAZBpZ3QzPYsu .image-shape .label,#mermaid-svg-ElnlAZBpZ3QzPYsu .icon-shape .label{text-align:center;}#mermaid-svg-ElnlAZBpZ3QzPYsu .node.clickable{cursor:pointer;}#mermaid-svg-ElnlAZBpZ3QzPYsu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .arrowheadPath{fill:#333333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ElnlAZBpZ3QzPYsu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ElnlAZBpZ3QzPYsu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ElnlAZBpZ3QzPYsu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster text{fill:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu .cluster span{color:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ElnlAZBpZ3QzPYsu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ElnlAZBpZ3QzPYsu rect.text{fill:none;stroke-width:0;}#mermaid-svg-ElnlAZBpZ3QzPYsu .icon-shape,#mermaid-svg-ElnlAZBpZ3QzPYsu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ElnlAZBpZ3QzPYsu .icon-shape p,#mermaid-svg-ElnlAZBpZ3QzPYsu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ElnlAZBpZ3QzPYsu .icon-shape .label rect,#mermaid-svg-ElnlAZBpZ3QzPYsu .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ElnlAZBpZ3QzPYsu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ElnlAZBpZ3QzPYsu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ElnlAZBpZ3QzPYsu :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 否
是
否
是
是
否
是
否
是
否
遇到 TS71007：Prop not serializable
当前文件是否声明了 use client？
检查父组件是否已声明 use client
当前文件应随父组件运行在客户端
检查报错来源是否真实存在跨边界传参
确认是否真的需要把该组件迁移到客户端
若需要，则补 use client 并调整 props
该文件是否为真正的客户端入口？
跨边界传入的 props 必须可序列化
函数、Date、Map 等需改为客户端内部生成
该文件只被客户端组件 import？
删除多余 use client
让它随父组件向下游传播
该文件既可能被服务端也可能被客户端引用？
将它显式声明为客户端边界
同时确保跨边界 props 可序列化
回到 B 重新确认依赖关系与使用场景
TS71007 消失
运行时行为不变
总结
TS71007 的核心不在 TypeScript 本身，而在于 Next.js 对客户端边界 props 的序列化约定。只要错误地给一个本应"随父组件运行"的叶子组件添加了 "use client"，就会人为制造一个不必要的 server → client 边界，触发函数类型 props 不可序列化的误报。
排查时应抓住一条主线：先确认谁才是真正的客户端入口 。入口组件保留 "use client"，被入口组件 import 的普通 UI 模块无需重复声明，让客户端身份自然向下游传播。这样既能消除 TS71007，也不会影响任何 hooks 的运行时能力。
如果后续在 DockBar、HelpTip、DispatchMask 等同类 widgets 上也看到相似报错，用同样的「边界审查」思路即可快速定位并修复。