如何为TypeScript配置*.graphql文件导入的类型声明包

需求可实现性说明 #

这个需求完全可以实现，当前报错由两处问题导致：类型声明文件存在笔误、使用项目未正确加载发布的类型包。

修复方案 #

第一步：修正类型包内的声明错误 #

你当前的graphql.d.ts中变量名和导出名不匹配，调整为如下内容：

declare module '*.graphql' {
  import { DocumentNode } from 'graphql';
  const defaultDocument: DocumentNode;
  export default defaultDocument;
}

如果需要支持按命名导出单个查询/片段，可以扩展为：

declare module '*.graphql' {
  import { DocumentNode } from 'graphql';
  const defaultDocument: DocumentNode;
  export const [对应查询名]: DocumentNode;
  export default defaultDocument;
}

调整后重新发布类型包即可。

第二步：配置使用项目的TypeScript规则 #

在引入这个类型包的项目中，二选一进行配置即可：

• 方式1：全局自动加载。在项目的tsconfig.json中添加types配置，指定加载你的类型包：

{
  "compilerOptions": {
    // 其他原有配置保留
    "types": ["@my-private-scope/type-graphql-imports"]
  }
}

• 方式2：手动按需引入。在项目的全局类型声明文件（通常为env.d.ts/global.d.ts）顶部添加引用声明：

/// <reference types="@my-private-scope/type-graphql-imports" />

额外校验项 #

如果配置完成后仍有报错，检查以下内容：

• 确认使用项目已经正确安装发布的@my-private-scope/type-graphql-imports包，版本匹配
• 确认tsconfig.json的include字段覆盖了.graphql文件存放的目录
• 如果使用vite/rollup等构建工具，需要配套安装.graphql文件的加载插件，避免运行时报错

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