如何将TypeScript内置类型暴露给JSDoc,解决ESLint报RequestInit未定义问题
解决JSDoc模式下ESLint无法识别TypeScript内置全局类型的问题
出现RequestInit类型未定义报错的核心原因是,ESLint的JSDoc插件即便开启了TypeScript解析模式,也不会主动加载TypeScript自带的全局类型定义文件(比如Web API对应的lib.dom.d.ts、ES标准对应的lib.es*.d.ts),不会自动关联TS的内置类型上下文,因此触发了no-undefined-types规则的检查报错。
可根据项目实际场景选择以下方案解决:
方案1:在单文件中显式引用内置类型库
直接在需要使用内置类型的文件顶部,通过TS三斜线引用标签指定需要加载的内置类型库,这个标签会被JSDoc插件的TypeScript模式识别:
// @ts-check /// <reference lib="dom" /> /** @type {RequestInit} */ const FETCH_OPTIONS = { cache: 'no-cache', credentials: 'include', method: 'GET', mode: 'cors' }; fetch('/api/getsomething/3', FETCH_OPTIONS) .then(nextFn) .catch(errorFn)
该方案改动最小,只需要在用到对应Web API类型的文件加一行引用,加载dom库后,RequestInit、Response、File等所有Web全局内置类型都会被正常识别。
方案2:在ESLint配置中添加预定义类型白名单
如果不想修改业务代码,可以直接在jsdoc/no-undefined-types规则的配置中,把需要用到的内置类型加入白名单,跳过这类类型的存在性检查:
// ESLint 配置片段 module.exports = { settings: { jsdoc: { mode: "typescript" } }, rules: { "jsdoc/no-undefined-types": ["error", { definedTypes: [ "RequestInit", "Response", "FetchEvent" // 其他需要跳过检查的内置类型可继续补充 ] }] } }
该方案的不足是如果后续用到其他未列在白名单里的内置类型,还是会触发报错,需要持续手动补充白名单,维护成本稍高。
方案3:关联项目TypeScript配置自动加载类型上下文
如果项目本身已经存在tsconfig.json文件,可以将ESLint的解析器替换为@typescript-eslint/parser,并在解析器配置中指定关联项目的tsconfig文件路径。配置完成后,ESLint的JSDoc插件会自动读取tsconfig中引入的所有类型声明(包括TypeScript默认加载的内置lib类型),无需额外加引用或列白名单,就能识别所有TS内置全局类型。
该方案是长期维护成本最低的,只要tsconfig里配置的lib字段包含项目需要的类型(大部分前端项目默认已经包含dom、esnext等常用库),就可以一劳永逸解决同类内置类型识别问题。
内容的提问来源于stack exchange,提问作者Kristian Roebuck
相关产品推荐
相关产品推荐

