混用毫秒与秒时，JsDoc能否帮我识别类型错误？

要让JsDoc定义的TSseconds和TSmilliSeconds触发类型检查，核心是用标称类型区分不同数值子类型，同时配置TypeScript的JS检查规则，具体步骤如下：

1. 定义标称类型而非简单别名 #

普通的@typedef {number} TSseconds只是类型别名，TypeScript会将其视为和number完全等价，无法区分。需要用交叉类型添加唯一标识来创建标称类型：

/**
 * 标称类型：秒数值
 * @typedef {number & { __brand: 'seconds' }} TSseconds
 */
/**
 * 标称类型：毫秒数值
 * @typedef {number & { __brand: 'milliseconds' }} TSmilliSeconds
 */

这个__brand属性是虚拟的，仅用于TypeScript区分类型，不会影响运行时。

2. 配置项目的检查规则 #

在项目根目录创建或修改jsconfig.json（纯JS项目）或tsconfig.json（TS/JS混合项目），开启JS文件的类型检查和严格模式：

{
  "compilerOptions": {
    "strict": true,
    "checkJs": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  },
  "include": ["**/*.js"]
}

• checkJs: 强制TypeScript检查JS文件中的JsDoc类型
• strict: 开启严格类型检查，放大类型不匹配的错误提示

3. 正确标注和使用类型 #

在变量、函数参数/返回值上明确标注自定义类型，TypeScript就会对混用情况触发警告：

/**
 * 秒转毫秒
 * @param {TSseconds} seconds
 * @returns {TSmilliSeconds}
 */
function convertSecToMs(seconds) {
  return seconds * 1000;
}

/** @type {TSseconds} */
const waitSec = 10;
/** @type {TSmilliSeconds} */
const waitMs = 10000;

// 以下代码会触发类型错误
convertSecToMs(waitMs); // 传入毫秒类型，不符合参数要求
setTimeout(() => {}, waitSec); // setTimeout需要毫秒，传入秒类型不匹配

4. 验证VS Code的TypeScript设置 #

• 打开VS Code设置，搜索TypeScript > Check: Enable，确保该选项处于开启状态
• 点击右下角状态栏的TypeScript版本，选择「Use Global TypeScript Version」，确保使用你安装的最新稳定版

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