如何让JSDoc/TypeScript识别JS导入？解决脚本标签导入报错

核心问题原因 #

使用普通<script src="imported-file.js"></script>引入文件时，VS Code的TypeScript检查器无法自动关联全局作用域中声明的函数类型——即便导入文件本身没有JSDoc错误，这种无模块边界的全局注入方式，TS无法追踪类型定义的来源，因此会抛出未定义错误。

VS Code中JSDoc/TypeScript对ES6导入方式的支持 #

1. <script type="module" src="imported-file.js"></script> #

完全支持。采用模块类型的script标签后，文件会以ES模块规范处理，通过明确的导出/导入建立类型关联：

• 在imported-file.js中导出目标函数：

  // imported-file.js
  /**
   * 示例工具函数
   * @param {string} msg 输出的提示信息
   * @returns {void}
   */
  export function showMessage(msg) {
    console.log(msg);
  }
  

• 在主文件中通过ES模块语法导入，同时确保主文件启用// @ts-check：

  // main.js
  // @ts-check
  import { showMessage } from './imported-file.js';
  showMessage('测试模块导入'); // 无类型错误，TS可识别函数类型
  

这种方式从根本上解决了全局变量的类型追踪问题，是推荐的做法。

2. 动态导入const myImportedModule = await import("imported-file.js"); #

同样完全支持。动态导入是ES6标准特性，VS Code的TS检查器能自动解析导入模块的类型：

• 使用示例（需在异步函数中执行）：

  // @ts-check
  async function loadUtils() {
    const { showMessage } = await import('./imported-file.js');
    showMessage('动态导入成功');
  }
  loadUtils();
  

动态导入返回Promise，因此必须在async函数或await上下文使用，TS会自动推导导入对象的类型。

非模块模式的替代方案 #

如果因场景限制无法切换到模块模式，可以通过JSDoc显式声明全局函数类型，避免// @ts-ignore的重复使用：

// @ts-check
/**
 * @global
 * @function showMessage
 * @param {string} msg 输出的提示信息
 * @returns {void}
 */

添加这段声明后，TS就能识别该全局函数的类型定义，不再抛出错误。

内置参考文档 #

VS Code内置了权威的JSDoc与TypeScript支持文档：

• 打开命令面板（Ctrl+Shift+P），输入TypeScript: Show JSDoc Reference，可查看官方JSDoc语法规范
• 查看TypeScript语言服务的内置提示：将鼠标悬停在JSDoc标签或TS语法上，可获取详细的用法说明

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