ES Modules 中 TypeScript 类型检查依赖编译时静态分析：文件需含 import/export 才被视为模块；可用 .d.ts 补全第三方类型；需配置 "module": "es2020" 和 "moduleResolution": "node16"；推荐使用 import type 和 verbatimModuleSyntax 提升准确性。
在 ES Modules（ESM）环境中结合 TypeScript 进行模块类型检查，关键不是“运行时检查”，而是靠 tsc 编译器在构建阶段静态分析 import/export 语句的类型兼容性。TypeScript 不改变 ESM 的加载机制，但通过类型声明、模块解析配置和编译时校验，确保模块导入导出的结构、类型和路径都正确无误。
确保文件被识别为模块
TypeScript 将任何含顶层 import 或 export 的文件自动视为模块（而非全局脚本），这是类型检查的前提：
- 哪怕只写
export {};，该.ts文件就进入模块作用域，内部声明默认不污染全局 - 没有
import/export的文件会被当作 script，其顶层变量会意外暴露，无法进行模块级类型隔离 - 例如：
utils.ts若只定义function formatDate() {...}却没导出，其他文件import { formatDate } from './utils'会报错 —— 不是因为 JS 执行失败，而是 TypeScript 在编译时就拒绝这种“不存在的导出”
用声明文件（.d.ts）补全第三方模块类型
很多纯 JavaScript 的 ESM 包（如 zod、valibot）自带类型，但若遇到无类型包，可通过以下方式让 TypeScript 知道它的导出结构：
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
- 在项目中新建
types/some-lib/index.d.ts，内容如：declare module 'some-lib' {<br> export const parse: (input: string) => number;<br> export default function validate(value: unknown): boolean;<br>} - 确保
tsconfig.json中"typeRoots"或"include"覆盖该目录，tsc 才能读取 - 这样即使
import validate from 'some-lib'是合法 ESM 语法，TS 也能校验validate(42)是否类型安全
配置 module 和 moduleResolution 匹配运行环境
类型检查是否准确，高度依赖 TypeScript 是否“理解”你实际使用的模块系统：
立即学习“Java免费学习笔记（深入）”；
-
"module": "es2020"或"esnext"：告诉 tsc 按 ESM 语法解析import/export，启用动态import()类型推断 -
"moduleResolution": "node16"（推荐）：启用 Node.js 16+ 的 ESM 解析规则，比如识别exports字段、支持.js和.ts后缀自动解析，避免“找不到模块”误报 - 若用
"moduleResolution": "node"（旧版），可能无法正确解析带"exports"的现代包，导致类型检查失效
利用类型导入（import type）避免循环与冗余
ESM 允许仅用于类型的导入，既不生成运行时代码，又参与类型检查：
-
import type { Config } from './config';：只读取类型信息，不引入值，防止无意中触发副作用或循环依赖 -
import { Component } from 'react'; import type { FC } from 'react';：值导入 + 类型导入分离，清晰表达意图 - 配合
"verbatimModuleSyntax": true（TS 5.0+），可禁用自动补全.js后缀等隐式行为，让路径解析更透明、更可控
