如何在VSCode的HTML内联脚本中引用外部类型定义？

我来帮你搞定这个问题！你已经在HTML里启用了// @ts-check，内联的JSDoc类型能正常工作，但想把类型抽出来复用却碰了壁——其实是之前的方法没踩对VSCode类型识别的点，下面给你两个亲测有效的方案：

方案1：用ES模块方式导入JSDoc类型 #

这个方案适合想保留JSDoc风格、不想写纯TS声明文件的场景：

1. 创建外部类型文件types.js，用模块导出类型（哪怕只是导出类型，也要加export让VSCode识别为模块）：

// types.js
/**
 * @typedef {Object} SpecialType
 * @property {number} prop1 - a number
 */
// 导出类型（不需要实际值，只是让模块生效）
export { SpecialType };

2. 在index.html的内联脚本里，用import()语法引用这个类型：

<script>
// @ts-check
/** @type {import('./types.js').SpecialType} */
const x = { prop1: 'invalid number' }; // 现在VSCode会正确提示类型错误
</script>

原理：VSCode的TypeScript服务能识别ES模块的类型导入，这样外部文件里的JSDoc类型就能被内联脚本复用了。

方案2：用全局TS声明文件（.d.ts）实现全局类型 #

如果你想让类型在整个项目（包括HTML内联脚本）里全局可用，这个方案更合适：

1. 创建global.d.ts声明文件，把类型放到全局作用域：

// global.d.ts
declare global {
  type SpecialType = {
    prop1: number;
  };
}
// 必须加这行，让TS把这个文件当成模块处理
export {};

2. 在项目根目录创建tsconfig.json（如果还没有的话），配置TypeScript服务扫描你的HTML和声明文件：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "allowJs": true,
    "checkJs": true // 开启JS文件的类型检查，对应HTML里的// @ts-check
  },
  "include": [
    "index.html",
    "global.d.ts"
  ]
}

3. 回到index.html的内联脚本，直接使用全局类型即可：

<script>
// @ts-check
/** @type {SpecialType} */
const x = { prop1: 'invalid number' }; // 类型错误会被正常识别
</script>

为什么你之前的方法没用？ #

简单说下你踩的坑：

• 方法1：直接用<script>引入types.js，VSCode不会自动把这个脚本里的类型关联到内联脚本——因为内联脚本默认在全局作用域，但非模块脚本的类型不会被主动识别为可复用的类型；
• 方法2：<link rel="import">是早就被废弃的HTML Imports标准，现在浏览器和VSCode都不支持了；
• 方法3：缺少tsconfig.json配置，或者global.d.ts的写法不对（没加declare global和export {}），导致VSCode没把它当成全局声明文件扫描。

内容的提问来源于stack exchange，提问作者a.xin