如何在非模块化多文件网站中使用VS Code的@ts-check并识别全局作用域？

我完全懂你的需求——要一个零打包、纯全局作用域的极简项目，双击index.html就能跑还没CORS问题，同时还想让VS Code的TypeScript工具链能正确识别跨文件的全局变量，支持跳转定义和类型检查对吧？下面是一套精准适配的方案：

1. 用jsconfig.json定义全局项目上下文 #

首先在项目根目录创建jsconfig.json，这个文件是告诉TypeScript你的JS项目的核心规则，重点是强制所有文件处于同一个全局作用域：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "None", // 关键：禁用模块系统，让所有JS都在全局作用域运行
    "checkJs": true, // 全局开启JS文件的类型检查，效果等同于每个文件加@ts-check
    "noImplicitAny": false, // 可选，如果你不想强制所有变量都必须有明确类型
    "strict": false // 可选，根据自己的代码严格程度调整
  },
  "include": [
    "*.js" // 替换成你的JS文件路径，比如文件都在src目录就写"src/**/*.js"
  ],
  "typeAcquisition": {
    "enable": true // 自动获取第三方库的类型定义（如果用到的话）
  }
}

2. 用/// <reference>指令模拟HTML加载顺序 #

虽然jsconfig.json能把所有文件纳入全局，但TypeScript默认不会自动推断index.html里的脚本加载顺序。为了让TS准确知道变量/函数的定义先后（避免出现"未定义"的虚假错误），你需要在依赖其他文件的JS顶部添加引用指令，指向它依赖的前置文件：

比如你的index.html加载顺序是：

<script src="utils.js"></script>
<script src="app.js"></script>
<script src="ui.js"></script>

那就在app.js顶部加：

/// <reference path="./utils.js" />
// 现在TypeScript明确知道app.js依赖utils.js，能识别utils里的全局变量

在ui.js顶部加：

/// <reference path="./utils.js" />
/// <reference path="./app.js" />

这样TS就能严格按照你指定的依赖顺序解析全局作用域，跳转定义的功能也会精准生效。

3. 配合@ts-check做单文件检查（可选） #

如果你不想全局开启checkJs，可以在需要类型检查的JS文件顶部单独加：

// @ts-check

结合上面的reference指令，依然能正常识别跨文件的全局变量。

4. 手动声明全局类型（可选） #

如果你的全局变量需要更明确的类型提示，可以在项目根目录创建globals.d.ts文件，手动声明全局类型：

declare global {
  interface Window {
    // 这里声明你的全局变量/函数
    formatDate: (date: Date) => string;
    appConfig: {
      theme: "light" | "dark";
      version: string;
    };
  }
}

export {}; // 必须加这行，让TS识别这是一个模块声明文件

这样VS Code会给这些全局变量提供完整的类型提示和跳转支持。

验证效果 #

做完以上配置后：

• 点击任意JS文件里的全局变量/函数，能直接跳转到它的定义文件
• TypeScript会按照你指定的顺序检查依赖，不会再出现"变量未定义"的虚假错误
• 双击index.html依然能正常运行，完全不需要服务器或打包工具

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