如何让npm run build成功编译FileSystemDirectoryHandle.entries()？

问题复现 #

用npx create-next-app@latest创建Next.js项目后，在page.tsx的Home()组件中加入以下代码：

navigator.storage.getDirectory()
.then(filesystem => filesystem.entries())
.then(entries => {});

执行npm run build时触发类型错误：

Type error: Property 'entries' does not exist on type 'FileSystemDirectoryHandle'.

npm run dev可正常运行（因跳过TypeScript检查），尝试修改downlevelIteration、添加lib配置、用as any断言均未得到合理解决。

解决方案 #

1. 安装最新Web API类型定义 #

官方DOM类型定义可能滞后于新API，安装@types/web获取完整的Web API类型：

npm install @types/web --save-dev

2. 调整tsconfig.json配置 #

修改tsconfig.json的compilerOptions，确保包含必要的lib并引入@types/web：

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "types": ["web"],
    "downlevelIteration": true,
    // 保留其他原有配置（如target、module等）
  }
}

3. 手动补充类型定义（若上述步骤无效） #

在项目根目录创建types/global.d.ts文件，手动添加缺失的方法声明：

interface FileSystemDirectoryHandle {
  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
  keys(): AsyncIterableIterator<string>;
  values(): AsyncIterableIterator<FileSystemHandle>;
}

保存后重启TypeScript服务，类型错误即可消除。

原因说明 #

FileSystemDirectoryHandle.entries()属于File System Access API的特性，TypeScript内置的DOM类型定义可能未及时同步该方法。npm run dev模式下Next.js会跳过严格类型检查，因此不会报错。通过更新第三方类型定义或手动补全类型，可从根源解决类型不匹配问题，避免使用as any这种规避手段。

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