如何在npm项目中内置Ambient TypeScript类型供依赖包免导入使用

• 首先在你的工具包源码目录下新增全局类型声明文件，例如命名为ambient.d.ts，使用declare global块声明所有注入的全局符号，示例如下：

// ambient.d.ts
// 该行必须保留，用于让TS将此文件识别为模块，否则全局声明不生效
export {}

declare global {
  // 此处替换为你实际注入的所有全局变量、方法的类型定义
  function task(name: string, handler: () => Promise<void> | void): void
  function group(name: string, handler: () => void): void
  const runtimeVersion: string
}

• 修改工具包的tsconfig.json，开启declaration: true，确保编译时会自动导出所有.d.ts类型文件到输出目录。
• 修改工具包的package.json，将类型入口指向你刚才声明的全局类型文件路径，例如：

{
  "name": "你的工具包名",
  "version": "x.x.x",
  "main": "./dist/index.js",
  "types": "./dist/ambient.d.ts"
}

• 消费方安装你的工具包后，仅需在项目的tsconfig.json中compilerOptions.types数组内添加你的工具包名即可自动识别所有全局类型，和Jest的使用体验完全一致：

{
  "compilerOptions": {
    "types": ["node", "你的工具包名"]
  }
}

• 如果你希望消费方连这一步配置都可以省略，可以把全局类型文件放到工具包根目录的types/index.d.ts路径下，TypeScript 会自动扫描 node_modules 下包的types目录加载类型，绝大多数场景下不需要消费方额外配置。

注意事项：

1. 不要把需要手动导入的工具API的类型写到declare global块中，仅在此处声明注入的全局变量类型即可
2. 如果消费方自定义了tsconfig.json的typeRoots配置，需要确保node_modules路径在typeRoots数组内，否则会出现类型加载失败的问题
3. 全局类型文件内的export {}不可删除，否则TypeScript会将文件识别为脚本文件，全局声明不会生效

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