在使用 Gemini CLI、各类 AI SDK 或较新的前端与 Node 工具时，您可能会突然遇到类似如下的报错信息：
class EventSourceParserStream extends TransformStream {^ReferenceError: TransformStream is not defined
很多人的第一反应往往是：是不是这个库存在 bug？或者我的开发环境安装出了问题？甚至开始怀疑自己写的代码是否有误。
但实际上，这个错误与您的代码几乎毫无关系。
报错的本质：Node.js 版本过低导致 TransformStream 未定义
核心原因只有一个：当前使用的 Node.js 版本过低，无法支持 TransformStream 这一标准 API。
TransformStream 并非某个第三方库的私有对象，而是 Web Streams API 的核心组成部分。这套 API 的兼容情况如下：
- 浏览器环境中早已得到广泛支持
- 在 Node.js 中，直到 Node 18 才开始稳定内置
- Node 16 及更早版本默认不提供该接口
因此，当您在 Node 16 环境下运行依赖 Web Streams 的代码时，系统会直接抛出如下错误：
ReferenceError: TransformStream is not defined为什么近期更容易遇到这个 TransformStream 报错？
这类问题在近一年内明显增多，背后有其必然原因。越来越多的开发工具与 SDK（尤其是 AI 相关工具）开始：
- 全面采用 Web 标准 API（如 fetch、ReadableStream、TransformStream）
- 统一浏览器与 Node.js 的运行模型
- 不再为旧版 Node 提供兼容性兜底支持
例如 Gemini CLI 所依赖的 eventsource-parser，其内部已默认基于 Web Streams 实现。这揭示了一个重要趋势：
Node 18+ 正在成为新的“事实最低运行标准”
Node 20 则是当前最稳妥、最推荐的生产环境选择
为何「明明已经切换到 Node 20」，仍然会报 TransformStream 未定义？
这是该问题中最令人困惑的地方。许多开发者使用 nvm 管理 Node 版本，操作流程大致如下：
nvm use 20
node -v # v20.x.x表面看一切正常。但问题在于：nvm use 仅对“当前 shell 会话”生效。一旦出现以下任一情况：
- 新开了一个终端窗口
- 在 VS Code 中打开了新的终端面板
- 系统 shell 启动时未正确加载 nvm
Node 便会悄悄回退到系统自带的版本（通常为 16 或更低）。于是便产生了这种错觉：“我明明已经切到 20 了，为什么实际运行的还是 16？”
如何准确确认当前使用的 Node 版本？
遇到这个错误时，第一件要做的事不是检查代码，而是执行以下两条命令：
node -v
which node如果您看到的结果是：
v16.x.x- 路径显示为
/usr/bin/node或/usr/local/bin/node（笔者使用 macOS，此为系统默认路径）
那么可以确认：当前运行环境并未处于 nvm 管理之下。
正确且稳定的解决方案
1. 确保 nvm 随 shell 启动自动加载
请在 ~/.zshrc 文件中确认包含以下配置：
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"这是 nvm 能够正常生效的前提条件。
2. 将 Node 20 设置为默认版本
nvm install 20
nvm alias default 20这样做的意义在于：每次新开终端时，只要 nvm 被成功加载，就会自动启用 Node 20，无需再手动执行 nvm use。
3. 在 Node 20 环境下重新安装全局工具（关键步骤）
如果 Gemini CLI 或其他工具是在 Node 16 环境下安装的，即便后续切换到 Node 20，仍可能出现各种异常。稳妥的做法是：
nvm use 20
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli一个简单有效的判断标准
最后，为您提供一个一劳永逸的判断方法：新开一个终端，不执行任何额外命令，直接输入 node -v，如果显示的是 v20.x.x，那么这个问题就彻底解决了。
写在最后
TransformStream is not defined 这个错误，表面看起来像是代码层面的异常，但实际上它揭示的是一个更深层的问题：Node.js 运行环境已经迈入“新世代”，而本地开发环境却还停留在过去。升级 Node 版本并正确配置 nvm，是告别这类问题的根本之道。
