升级TypeScript 5.6 Beta遇Buffer类型兼容错误，如何解决？

问题描述 #

升级至TypeScript 5.6 Beta版本，未修改业务代码，却在node_modules中出现以下类型错误：

node_modules/@types/node/buffer.d.ts:632:19 - error TS2430: Interface 'Buffer' incorrectly extends interface 'Uint8Array'.
  The types returned by 'reverse()' are incompatible between these types.
    Type 'this' is not assignable to type 'Uint8Array'.
      Type 'Buffer' is not assignable to type 'Uint8Array'.
        The types returned by 'slice(...).entries()' are incompatible between these types.
          Type 'IterableIterator<[number, number]>' is missing the following properties from type 'BuiltinIterator<[number, number], undefined, any>': map, filter, take, drop, and 8 more.

632         interface Buffer extends Uint8Array {
                      ~~~~~~

node_modules/@types/node/fs/promises.d.ts:56:66 - error TS2344: Type 'Buffer' does not satisfy the constraint 'ArrayBufferView'.
  Type 'Buffer' is not assignable to type 'Uint8Array | DataView'.
    Type 'Buffer' is not assignable to type 'Uint8Array'.
      The types returned by 'entries()' are incompatible between these types.
        Type 'IterableIterator<[number, number]>' is missing the following properties from type 'BuiltinIterator<[number, number], undefined, any>': map, filter, take, drop, and 8 more.

56     interface FileReadOptions<T extends NodeJS.ArrayBufferView = Buffer> {
                                                                    ~~~~~~

node_modules/@types/node/fs/promises.d.ts:238:49 - error TS2344: Type 'Buffer' does not satisfy the constraint 'ArrayBufferView'.
  Type 'Buffer' is not assignable to type 'Uint8Array | DataView'.
    Type 'Buffer' is not assignable to type 'Uint8Array'.
      The types returned by 'entries()' are incompatible between these types.
        Type 'IterableIterator<[number, number]>' is missing the following properties from type 'BuiltinIterator<[number, number], undefined, any>': map, filter, take, drop, and 8 more.

238         read<T extends NodeJS.ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
                                                    ~~~~~~

注：更新至TypeScript 5.6正式版后，BuiltinIterator<[number, number], ...>已被ArrayIterator<number>替代。

错误原因 #

TypeScript 5.6 Beta对内置迭代器类型进行了重构，用新的ArrayIterator接口替换了旧的BuiltinIterator。而旧版本的@types/node类型定义未适配这一变化，导致Buffer与Uint8Array的类型兼容性校验失败。

修复方案 #

1. 更新@types/node到兼容版本 #

这是最彻底的解决方案：

• 执行命令安装最新版@types/node：

  npm install @types/node@latest --save-dev
  # 或使用yarn
  yarn add @types/node@latest --dev
  # 或使用pnpm
  pnpm add @types/node@latest --save-dev
  

• 建议选择明确标注支持TypeScript 5.6的版本（如v20.11.0及以后），可查看@types/node的版本发布说明确认适配情况。

2. 清理缓存并重新编译 #

更新依赖后，清理缓存确保新类型定义生效：

• 删除TypeScript缓存目录：

  rm -rf node_modules/.cache
  

• 重新安装依赖：

  npm install
  

• 重新编译项目：

  tsc
  

3. 临时规避方案（不推荐长期使用） #

如果暂时无法更新@types/node，可临时跳过库文件的类型检查：

• 在项目的tsconfig.json中添加配置：

  {
    "compilerOptions": {
      "skipLibCheck": true
    }
  }
  

• 注意：此方案会跳过所有第三方库的类型校验，可能掩盖其他真实的类型问题，仅作为临时过渡使用。

内容的提问来源于stack exchange，提问作者Daniel Rosenwasser