构建TypeScript JSX库时global.d.ts未输出至build目录求助

问题原因 #

global.d.ts属于环境声明文件（Ambient Declaration），这类仅包含类型声明、无任何导出/导入语句的文件，TypeScript默认不会将其单独输出到outDir目录，但它的类型会在编译阶段被识别。若你的库需要使用者能访问这些全局类型（比如自定义JSX类型），需确保类型被正确纳入最终的类型分发文件中。

解决方案 #

方案1：将全局声明转为模块并导入到入口 #

修改src/types/global.d.ts，添加空导出使其成为模块，TypeScript会将其编译为独立的.d.ts文件输出到build目录：

export {};

declare global {
  // 你的全局类型定义

  namespace JSX {
    // 你的JSX类型定义
  }
}

在库入口文件（如src/index.ts）中导入该文件，确保使用者导入你的库时能加载这些全局类型：

import './types/global.d.ts';

执行npm run build后，可在build/types/目录下看到global.d.ts，且全局类型会正常生效。

方案2：用三斜杠引用合并类型到入口声明 #

若不想修改global.d.ts的结构，可在入口文件src/index.ts顶部添加三斜杠引用，让TypeScript将全局类型合并到输出的index.d.ts中：

/// <reference path="./types/global.d.ts" />

// 你的库代码导出逻辑

这种方式下，global.d.ts不会单独输出，但它的类型定义会被包含在build/index.d.ts中，使用者通过库的类型入口即可访问这些全局类型。

方案3：确认tsconfig配置有效性 #

检查tsconfig.build.json是否意外排除了global.d.ts：当前配置仅排除测试文件和src/dev，继承自tsconfig.json的include规则已覆盖该文件，无需调整。同时确保compilerOptions中的declaration为true（你的配置已开启），这是生成类型声明文件的必要条件。

验证 #

执行npm run build后：

• 方案1：查看build/types/global.d.ts是否存在且内容正确。
• 方案2：查看build/index.d.ts是否包含global.d.ts中的类型定义。

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