DEBUG.WIKI
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国
搬瓦工;先看线路,再选 VPS;CN2 GIA · 对应线路套餐;查看线路 →
V.PS:让项目靠近用户,亚太、欧洲、北美 KVM VPS

thread-stream 编译报 TS2694,Node 26 类型没有 TransferListItem

thread-stream4.2.0仍使用已从Node26类型中删除的别名。按真实运行时选择类型包,确需26时以可审计声明补丁改为Transferable。

升级 Node 类型声明后,应用没有修改 worker 代码,TypeScript 却在 thread-stream 的声明文件里报错:

TS2694: Namespace '"worker_threads"' has no exported member 'TransferListItem'.

thread-stream 4.2.0 的 message 事件重载仍使用 workerThreads.TransferListItem[]。@types/node 26 删除了这个旧别名,继续公开 Transferable;因此错误发生在声明兼容层,不表示实际日志 worker 已经丢失传输能力。

先核对运行时和实际加载的类型包

运行中的 Node 版本与 TypeScript 使用的 @types/node 是两个独立版本。先确认构建配置、锁文件、工作区依赖与实际解析位置,不要因为类型包显示 26,就认定部署环境也是 Node 26。

如果项目实际运行 Node 24,却无意安装了 26 的类型,应按项目依赖政策选择与目标运行时相符的声明,并重新检查全部消费代码。不能把“退类型包”当成 Node 26 项目的通用答案;那可能让代码依赖运行时没有的接口,或漏掉当前接口变化。

正式 @types/node 24.10.0 同时提供 Transferable 和已弃用的 TransferListItem 别名;26.6.5 只提供前者。thread-stream 4.2.0 当前仍引用旧名。

确实需要 Node 26 类型时,限定声明补丁

若依赖暂时没有包含这项兼容修正的正式发行,可用项目包管理器支持的补丁机制,只修改该重载里的类型名称:

- emit(eventName: 'message', message: any, transferList?: workerThreads.TransferListItem[]): boolean
+ emit(eventName: 'message', message: any, transferList?: workerThreads.Transferable[]): boolean

保存补丁、目标包版本与锁文件,使干净安装能重复应用,并在升级依赖时重新核对补丁是否仍需要。不要只编辑本机 node_modules,留下 CI 和部署环境仍报错的差异。

这项修改不改变实际传输逻辑,也不把任意对象变成可转移对象。ArrayBuffer、MessagePort 等仍需符合运行时的传输规则;SharedArrayBuffer 不是靠加入 transferList 来转移所有权。不要为了过编译把整条重载改成 any[],或给 worker_threads 全局声明一个与实际接口不同的别名。

编译通过后仍核对消息行为

保持 skipLibCheck 为项目原有严格设置,检查库声明和实际消费代码,再通过已有日志入口核对 worker 启动、message 参数及关闭清理。需要测试转移时使用隔离数据,确认发送端与接收端的所有权行为符合原约定,不拿业务正在使用的缓冲区做破坏性试验。

若报错来自应用导入了 Pino 未公开的类型,则属于namespace 类型出口变化,不能用本文替换 thread-stream 别名解决。这里只针对错误指向 thread-stream/index.d.ts,并且缺少的名字确为 TransferListItem 的组合。