普通JS文件使用TypeScript检查与声明且无需转译的方案咨询

你遇到的报错核心原因是declare、interface等属于TypeScript专属语法，不能直接写在运行时加载的.js文件中，既无法通过TS的文件类型校验，Node运行时也会把这类语法识别为非法JS语法。以下是符合你需求的两种解决方案：

该方案所有类型信息都放在JS注释或者独立的类型声明文件中，不会侵入JS运行时代码，完全不需要转译步骤，完美匹配你不想编译的要求。

• 第一步：调整tsconfig.json配置

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true, // 开启对JS文件的类型校验
    "noEmit": true, // 完全不输出任何转译后的文件，仅做类型校验
    "target": "ESNext", // 和你Node环境支持的语法版本对齐即可
    "module": "NodeNext"
  },
  "include": ["**/*.js", "**/*.d.ts"] // 包含你的业务JS文件和类型声明文件
}

• 第二步：将TS专属语法从JS文件中剥离
  类型声明相关的代码不要写在业务.js文件里，统一放到项目根目录的global.d.ts独立声明文件中，比如你示例里的模块声明直接写在该文件即可：

declare module "something" {
    export interface MyInterface {
        // 接口字段定义
    }
}

该文件仅会被TS识别用于类型校验，Node运行时完全不会加载，不会触发语法报错。

• 第三步：JS文件内的类型标注用JSDoc实现
  如果需要在JS代码里标注变量、参数、返回值类型，直接写在注释中即可，TS会自动识别做校验，运行时注释会被忽略不会影响执行：

/**
 * @param {import('something').MyInterface} data 
 * @returns {Promise<{code: number, msg: string}>}
 */
function handleData(data) {
  // 此处TS会自动校验data的类型，以及返回值是否符合定义
}

如果你实在习惯直接写TS类型语法，不想用JSDoc，可以用Babel的TS预设，配置成仅移除类型语法，不对原生JS语法做任何转译，生成的代码和你写的源码几乎完全一致，没有额外生成的辅助函数，行号完全对应，处理速度极快。

• 安装依赖：npm install @babel/core @babel/cli @babel/preset-typescript -D
• 根目录新建babel.config.json配置文件：

{
  "presets": [
    ["@babel/preset-typescript", {
      "allowDeclareFields": true,
      "onlyRemoveTypeImports": true
    }]
  ]
}

• 把你的.js文件后缀改成.ts，执行babel src --out-dir dist --extensions ".ts"即可生成和源码几乎一致的JS文件。开发阶段可以搭配babel-node作为运行器，直接运行TS文件，自动实时剥离类型，不会生成多余的中间文件。

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