TypeScript 5.x使用typeRoots时@types/wicg-file-system-access失效问题

问题背景 #

将TypeScript从4.9版本迁移至5.7版本后，配置了typeRoots的项目中，@types/wicg-file-system-access类型库出现加载异常，编译时触发类型报错。

根因分析 #

该类型库通过package.json的typesVersions字段为不同TS版本提供适配类型：

"types": "index",
"typesVersions": {
    "<=5.0": {
        "*": [
            "ts5.0/*"
        ]
    }
},

逻辑上，TS版本>5.0时应加载根目录的index类型文件，但TypeScript的typeRoots配置会忽略第三方库自身的typesVersions分支逻辑，导致类型加载路径匹配错误，进而触发报错。

当前项目的TypeScript配置片段：

{
  "compilerOptions": {
    "typeRoots": ["libs/sdk/types", "node_modules/@types"],
    "types": [
            "node",
            "typelevel",
            "react-util-types",
            "browser-compat",
            "@types/wicg-file-system-access",
            "office-js"
        ],
  }
}

可行解决方案 #

方案1：移除typeRoots配置（推荐） #

如果项目中libs/sdk/types下的自定义类型可通过代码直接导入，移除typeRoots后，TS会默认处理第三方库的typesVersions逻辑，自动匹配对应版本的类型文件：

{
  "compilerOptions": {
    "types": [
            "node",
            "typelevel",
            "react-util-types",
            "browser-compat",
            "@types/wicg-file-system-access",
            "office-js"
        ],
  }
}

方案2：显式指定类型文件路径 #

保留typeRoots配置的同时，直接指定该库对应TS5.0+的类型文件路径，绕过typesVersions的自动匹配：

{
  "compilerOptions": {
    "typeRoots": ["libs/sdk/types", "node_modules/@types"],
    "types": [
            "node",
            "typelevel",
            "react-util-types",
            "browser-compat",
            "@types/wicg-file-system-access/index",
            "office-js"
        ],
  }
}

方案3：复制适配类型到自定义目录 #

将@types/wicg-file-system-access根目录下的所有类型文件复制到项目的libs/sdk/types/wicg-file-system-access目录中，让typeRoots优先加载自定义目录下的适配类型，避免依赖库的typesVersions逻辑。

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