ViteToNext.AI 为何自动注入 'use client'，以及何时会出错
译注：本文翻译自 dev.to 文章《'use client' Injection: Why ViteToNext.AI Adds It Automatically (And When It Gets It Wrong)》，作者 digitaldev，原文发布于 2026-09-23。原文链接见文末。
引言
如果你最近尝试把一个标准的基于 Vite 的 React 应用迁移到 Next.js（尤其是 App Router），很可能已经撞上了那个令人头疼的“Server Component Error”。通常，这是因为你在一个被 Next.js 判定为 Server Component 的文件里使用了 useState、useEffect，或者像 onClick 这样的事件监听器。
在 Vite 生态里，默认一切都是客户端组件；而在 Next.js App Router 中，默认恰恰相反。这一根本性转变要求开发者在文件顶部加上 'use client' 指令。理论上很简单，但当你要迁移成百上千个文件时，这就变成了一场后勤噩梦。
'use client' 的设计哲学
在讨论自动化之前，必须先理解 'use client' 到底意味着什么。与流行的误解相反，它并不表示组件只在客户端运行，而是标记了“仅服务端代码”与“可在客户端 hydrate 的代码”之间的边界。
从 Vite 迁移到 Next.js 时，你的整个组件树本质上是“服务端优先”的。要维持 Vite 应用现有的交互性，就必须找出每一个触及 DOM API 或维护状态的组件。
自动化工具为何默认注入 'use client'
迁移大型项目时，人工逐个文件排查 useEffect 钩子极易出错。因此，像 ViteToNext.AI 这样的自动化迁移工具，通常会分析你的 import 和 hook 使用情况，在检测到交互逻辑的地方自动注入 'use client' 指令。
自动化的目标是解决“白屏”问题。如果工具不注入这些指令，迁移后的应用根本无法编译，会立刻抛出成百上千个错误。通过识别 React 钩子（useState、useContext）以及浏览器特有的全局变量，自动化脚本能确保应用在过渡阶段保持可用。
注入出错的情况
自动化虽然能救急，但并非完美。以下三种场景中，自动注入器可能会判断失误：
1. “叶子组件”谬误
自动化往往会在尽可能高的层级注入 'use client' 以确保功能正常，但这常常让父组件不必要地变成客户端组件。在理想的 Next.js 架构中，应当让负责数据获取的父组件留在服务端，把交互性下沉到尽可能小的“叶子”组件。自动化可能过度应用该指令，导致客户端 bundle 比实际需要更大。
2. 组合模式
考虑一个接收 {children} 的布局组件。在 Vite 中它只是普通组件；在 Next.js 中，如果这个组件因为包含一个小开关而被标记为客户端组件，那么作为 children 传入的组件并不一定是客户端组件，但这种交织关系会让静态分析工具感到困惑。如果工具误判了边界，你可能就会失去在这些 children 中进行服务端数据获取的能力。
3. 第三方库封装
许多遗留 UI 库（如旧版 MUI 或专用图表库）尚未在自己的导出中包含 'use client' 指令。自动化工具可能看到一个来自库的 Button import，却没意识到需要该指令的是库本身，结果即使你自己的代码是“纯净”的，也会报错。
手动清理策略
自动化迁移之后，应当执行一次“组件审计”：
- 搜索
'use client'：列出所有带该指令的文件。 - 检查数据获取：如果某个标记为
'use client'的组件同时通过fetch()或Axios进行繁重的async数据获取，考虑把该逻辑移到 Server Component，并以 props 向下传递数据。 - 最小化边界：如果一个 500 行的组件仅仅为了一个
onClick处理器就被标记为客户端组件，把这个按钮重构到独立文件，并从父组件移除该指令。
结语
从 Vite 纯客户端的世界转向 Next.js 的混合环境，是现代 React 开发中最大的门槛。自动注入 'use client' 是让应用快速跑起来的必要桥梁，但最终的打磨——为性能和 SEO 做优化——仍然需要开发者亲自把关，确保服务端与客户端的边界落在正确的位置。