发布含全局TypeScript声明的npm包，外部无法识别需如何配置？

TypeScript 默认会自动加载 node_modules/@types 目录下的所有类型定义，但对于不在该目录下的自定义包，不会自动扫描其全局类型——这就是你遇到问题的核心原因。以下是具体的配置方案和说明：

包端配置要点 #

首先确保你的包本身的类型声明和配置是正确的：

1. 正确编写全局类型声明

   • 如果类型文件没有任何 import/export 语句，直接声明全局变量即可：

     // index.d.ts
     declare var thisIsAGlobal: string;
     

   • 如果类型文件依赖其他模块（存在 import/export），必须将全局声明包裹在 declare global 块中：

     // index.d.ts
     import { SomeDependencyType } from './dependency';
     
     declare global {
       var thisIsAGlobal: SomeDependencyType;
     }
     
     // 可选：导出空对象确保文件被识别为模块（已有import/export时可省略）
     export {};
     

2. 配置 package.json 类型入口
   在包的 package.json 中明确指定类型文件路径：

   {
     "name": "my-package",
     "types": "./index.d.ts",
     "typings": "./index.d.ts" // 可选，与types字段作用一致
   }
   

消费端自动识别配置 #

要让项目无需手动 import 或 /// <reference types="my-package" /> 就能识别全局类型，需要在消费项目的 tsconfig.json 中做以下任一配置：

1. 指定自动加载的类型包
   在 compilerOptions.types 数组中添加你的包名，TypeScript 会自动加载该包的类型定义：

   {
     "compilerOptions": {
       "types": ["my-package"]
     }
   }
   

2. 扩展类型扫描根目录（不推荐）
   修改 typeRoots 让 TypeScript 扫描所有 node_modules 下的类型文件，但这种方式会加载所有依赖的类型，可能导致性能下降或类型冲突：

   {
     "compilerOptions": {
       "typeRoots": ["node_modules/@types", "node_modules"]
     }
   }
   

补充说明 #

• 若希望完全无需消费端配置就能自动识别，唯一的原生方式是将类型发布到 @types 组织下（即 @types/my-package），这需要遵循 DefinitelyTyped 的贡献流程，适合第三方开源库的类型维护。
• 若你的包同时提供全局变量和模块导出，可将全局声明单独放在一个无 import/export 的类型文件中，并在 package.json 的 types 字段指向该文件，同时保留模块导出的类型定义。

内容的提问来源于stack exchange，提问作者David De Anda