如何让WebStorm在JavaScript文件中不忽略TypeScript类型信息？

我正在使用WebStorm 2022.2（版本号#WS-222.3345.108），在新建空项目中已将ethers.js添加为自定义第三方库。HTML内嵌脚本里，WebStorm能正确识别带JSDoc注解的TypeScript类型，提供代码补全、跳转等功能，甚至TypeScript特有的ContractTransaction接口也能正常工作。但将相同代码放入外部index.js文件时，WebStorm完全忽略TypeScript声明，引发以下问题：

• 误将Contract类型指向JS文件，无法识别其索引签名，报错“Unresolved function or method myMethod()”
• 对ContractTransaction类型注解报错“Unresolved variable or type 'ContractTransaction'”
• 能识别tx.wait()方法的声明，却无法找到ContractTransaction类型，仅提示“Promise returned from wait is ignored”

请问如何让WebStorm在外部JavaScript文件中，像在HTML内嵌脚本中一样利用TypeScript类型信息？

1. 配置JavaScript语言与类型检查 #

打开WebStorm的Settings/Preferences（快捷键Ctrl+Alt+S），依次进入Languages & Frameworks > JavaScript：

• 将JavaScript language version设置为ECMAScript 6+或更高版本
• 勾选Enable TypeScript type checking选项
• 确保Allow JavaScript files to be compiled处于开启状态

2. 确认ethers.js类型声明的有效性 #

• 优先通过npm安装ethers.js（执行npm install ethers），npm包内置了完整的TypeScript类型声明，比手动添加自定义库更可靠
• 如果是手动添加的自定义库，进入Settings/Preferences > Languages & Frameworks > JavaScript > Libraries，选中ethers.js库，检查是否包含.d.ts类型声明文件，并且已勾选Enable；若未识别，点击Rescan重新扫描库文件

3. 在JS文件中通过JSDoc显式引入类型 #

在外部index.js文件的顶部，添加JSDoc注解来导入ethers的类型：

/**
 * @typedef {import('ethers').Contract} Contract
 * @typedef {import('ethers').ContractTransaction} ContractTransaction
 */

或者在使用类型的变量前直接标注：

/** @type {ContractTransaction} */
let transaction;

4. 添加tsconfig.json配置文件 #

在项目根目录创建tsconfig.json，写入以下内容：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "module": "ESNext",
    "target": "ES6",
    "moduleResolution": "Node"
  },
  "include": ["index.js"] // 替换为你的外部JS文件路径，可使用通配符如"*.js"
}

这个配置会让WebStorm以TypeScript的类型规则解析JavaScript文件，自动识别依赖的类型声明。

5. 清除缓存并重启WebStorm #

点击File > Invalidate Caches...，选择Invalidate and Restart，解决因缓存导致的类型识别异常问题。

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