如何验证手写.d.ts文件的正确性？VSCode能否给出相关警告？

问题场景 #

假设你有以下文件结构：

src/
  my-module.js
  my-module.d.ts
  index.ts

my-module.js代码：

const thing = 42;
module.exports = { thing };

my-module.d.ts原本定义：

export declare const thing: number;

如果把.d.ts里的thing类型改成string，VSCode在三个文件里都不会给出任何警告——这就是需要解决的核心问题：怎么让类型定义和实际JS代码不匹配时，编辑器能主动提示冲突？

解决方法 #

1. 开启TypeScript全局JS类型检查 #

在项目根目录的tsconfig.json中配置以下选项，让TypeScript直接校验JS文件的类型，并对比.d.ts定义是否一致：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "strict": true // 可选，开启严格模式强化类型校验力度
  },
  "include": ["src/**/*"]
}

开启后，若.d.ts里的类型和JS实际值不匹配（比如把thing定义为string但实际是数值42），VSCode会直接在.d.ts或JS文件中弹出类型不匹配的警告。

2. 单文件快速开启类型检查 #

如果不想全局启用JS校验，可以在目标JS文件顶部添加注释，单独开启该文件的类型检查：

// @ts-check
const thing = 42;
module.exports = { thing };

这样当.d.ts定义和JS实际代码冲突时，编辑器会立即给出提示。

3. 自动生成准确的.d.ts文件 #

如果不想手写类型定义，可利用TypeScript的类型推断自动生成完全匹配的.d.ts文件：
在终端运行以下命令（需已安装TypeScript）：

tsc my-module.js --declaration --allowJs --emitDeclarationOnly

该命令会根据JS文件的实际代码生成对应的类型定义，后续JS代码更新时，重新运行命令即可同步更新.d.ts，从根源避免手写错误。

4. 在TS使用端添加类型校验测试 #

在引入模块的index.ts中，可通过类型断言测试验证类型定义是否正确：

import { thing } from "./my-module";
console.log(thing);

// 若.d.ts定义错误，此处会直接报错
const test: string = thing; // 比如.d.ts错误定义为string，但实际是number，这里会提示类型不兼容
type TypeOfThing = typeof thing;

这种方式能快速在模块使用环节发现类型定义的问题。

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