在使用 Gemini CLI、一些 AI SDK，或者较新的前端 / Node 工具时，你可能会突然遇到这样一段报错：
class EventSourceParserStream extends TransformStream {
^
ReferenceError: TransformStream is not defined
第一反应往往是：
是不是库有 bug？是不是我环境装坏了？甚至开始怀疑是不是代码写错了。
但实际上，这个错误和你的代码几乎没有关系。
报错的本质：Node.js 版本不支持
这个问题的核心原因只有一个：
当前使用的 Node.js 版本过低，不支持 TransformStream。
TransformStream 并不是某个第三方库私有的对象，而是 Web Streams API 的一部分。
而这套 API：
- 在浏览器中很早就存在
- 在 Node.js 中，直到 Node 18 才开始稳定支持
- Node 16 及更早版本中，默认是不存在的
所以当你在 Node 16 环境下运行依赖 Web Streams 的代码时，就会直接抛出：
ReferenceError: TransformStream is not defined
为什么最近更容易遇到这个错误？
这类问题在近一年明显变多，其实是有背景原因的。
越来越多的工具和 SDK（包括 AI 相关工具）开始：
- 使用 Web 标准 API（fetch、ReadableStream、TransformStream）
- 统一浏览器和 Node 的运行模型
- 不再为旧 Node 版本做兼容兜底
比如 Gemini CLI 使用的 eventsource-parser，内部已经默认依赖 Web Streams。
这意味着一个事实：
Node 18+ 正在成为新的“事实最低标准”
Node 20 则是当前最稳妥的选择
那为什么「我明明切过 Node 20」，还是会报错？
这是这个问题里最容易让人困惑的地方。
很多人使用的是 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（笔者用的是 mac，所以这是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 运行环境已经进入“新世代”，但本地环境还停留在旧版本。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。
如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。
注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。
使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！
