如何在非TypeScript文件中仅对特定JSDoc标注对象做类型检查？

要实现只对带有JSDoc类型标注的对象做类型检查，同时忽略遗留代码的报错，可以通过以下两种方式配置：

一、使用tsconfig.json精准控制检查范围 #

在项目根目录创建tsconfig.json，配置如下：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "skipLibCheck": true,
    "noImplicitAny": false,
    "strictNullChecks": false,
    "noImplicitReturns": false,
    "noImplicitThis": false,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "onlyCheckTypedDeclarations": true
  },
  "include": ["你的JS文件路径/**/*.js"]
}

关键配置说明：

• allowJs + checkJs：开启对JS文件的类型检查
• noEmit：仅做检查，不生成TS编译产物
• strict: false + 关闭一系列严格规则：避免遗留无类型标注的代码触发报错
• onlyCheckTypedDeclarations: true：核心开关，TypeScript仅检查带有JSDoc类型标注（比如@type、@typedef）的变量、函数等，未标注的代码不做校验

配置完成后，无需在文件顶部加// @ts-check，编辑器会自动识别tsconfig，对标注了JSDoc的对象进行类型校验（比如你示例中notes:12会因类型不匹配报错），遗留代码不会触发红线。

二、单文件局部配置（适合少量文件场景） #

如果不想全局配置，可在目标文件顶部添加// @ts-check，然后对不需要检查的代码行/块添加// @ts-ignore忽略报错：

// @ts-check

/** @typedef { import("./types").Requests } Requests */

/** @type Requests */
const theReq = {
    notes: 12,  // 这里会触发类型报错，符合预期
}

// @ts-ignore
const legacyVar = someUnTypedFunction(); // 该行不会触发检查报错

但这种方式需要逐个处理遗留代码，适合文件数量少的场景。

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