TypeScript无顶层import/export文件视为全局脚本的含义疑问

首先明确文档中提到的*global scope（全局作用域）*需要从TS类型检查、JS运行时两个层面拆分理解，你的报错是类型检查层面的配置问题，并非规则不成立：

核心规则解释 #

在TypeScript中，和ES2015规范一致，任何包含顶层import或export的文件都会被判定为模块；反之没有顶层import/export的文件会被判定为脚本，内容属于全局作用域，模块也可以直接访问。
这里的全局作用域具体指：

• 类型检查层面：脚本文件的顶层变量、函数的类型定义会被纳入TS的全局类型上下文，所有纳入TS扫描范围的文件都可以直接识别这些类型，不需要额外导入
• 运行时层面：脚本文件的顶层变量、函数会被挂载到宿主环境的全局对象上（浏览器是window，Node.js是global，通用可以用globalThis访问），只要运行时先加载了脚本的编译产物，后续加载的代码都可以直接调用

你碰到TS2304报错的原因 #

你无法直接调用add函数且收到报错，本质是TS没有把你的global.ts纳入全局类型扫描范围，和规则本身无关，常见触发原因有两个：

1. tsconfig.json的include字段没有覆盖到global.ts，TS类型检查时根本没扫描到这个文件的定义，自然识别不到add函数
2. 你使用了Vite、Webpack等打包工具，这类工具默认会把所有项目文件都当作模块处理，哪怕没有顶层import/export，此时global.ts的顶层定义不会自动挂载到全局对象

解决方案 #

场景1：未使用打包工具，原生TS编译 #

只需要修改tsconfig.json，确保include字段包含global.ts所在目录即可，示例配置：

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "ESNext"
  },
  "include": ["src/**/*"] // 所有src下的文件都会被扫描，global.ts如果在src下就能被识别
}

场景2：使用了打包工具 #

需要显式把add挂载到全局对象，同时声明全局类型：

// global.ts 代码
function add(a: number, b: number): number {
  return a + b
}
// 显式挂载到全局对象
globalThis.add = add

// 声明全局类型，让TS识别全局的add
declare global {
  function add(a: number, b: number): number
}

如果不需要global.ts是模块，可以去掉所有顶层import/export，也不需要declare global块，只要打包工具配置了排除该文件按脚本处理即可。 #

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