tsc编译GraphQL+Node.js+TS服务启动报错：Unknown type 'Query'

问题根源分析 #

你遇到的Unknown type "Query"错误，核心是GraphQL构建可执行Schema时，未能正确读取到Query类型的定义。结合你的编译流程（tsc编译+ Babel处理路径别名），问题大概率出在以下几个环节：

1. 路径别名转换不彻底 #

虽然你配置了typescript-transform-paths和babel-plugin-module-resolver，但两者的转换范围可能没覆盖到GraphQL相关的导入逻辑。比如代码中用import typeDefs from 'src/graphql/typeDefs'这类别名导入时，编译后路径未正确转为相对路径，导致typeDefs加载为空或错误，最终缺失Query定义。

2. GraphQL静态文件未被复制到dist目录 #

如果你的typeDefs写在.graphql后缀的文件中，tsc默认不会处理这类静态文件，编译后dist目录中缺失这些文件，运行时无法读取到类型定义。

3. Schema构建参数在编译后异常 #

编译后的typeDefs可能变成undefined、空数组，或者resolvers与typeDefs的关联被破坏，导致Schema构建时无法识别Query类型。

分步解决方案 #

第一步：排查编译后的Schema文件 #

先打开dist/graphql/schema.js，定位到报错的第11行（makeExecutableSchema调用处）：

• 如果typeDefs是undefined或空数组：说明类型定义未正确加载
• 如果typeDefs有内容：检查是否包含type Query { ... }的完整定义

第二步：修复路径别名转换配置 #

调整Babel的module-resolver配置，确保覆盖所有src/开头的路径别名：

// .babelrc
{
  "compact": false,
  "retainLines": true,
  "minified": false,
  "inputSourceMap": false,
  "sourceMaps": false,
  "plugins": [
    [
      "module-resolver",
      {
        "root": ["./dist"],
        "alias": {
          "src/*": "./dist/*" // 用通配符匹配所有src开头的路径
        }
      }
    ]
  ]
}

同时确认typescript-transform-paths已正确安装并配置：

npm install typescript-transform-paths --save-dev

第三步：复制GraphQL静态文件到dist #

如果使用独立的.graphql文件存类型定义，需要在编译时同步复制这些文件：

1. 安装copyfiles工具：

npm install copyfiles --save-dev

2. 修改package.json的build脚本：

"scripts": {
  "build": "tsc && copyfiles -u 1 src/**/*.graphql dist && babel dist -d dist"
}

该命令会将src目录下所有.graphql文件复制到dist对应路径中。

第四步：优化GraphQL类型定义的导出方式 #

推荐用graphql-tag定义typeDefs，确保编译后依然是有效的DocumentNode类型，避免字符串格式问题：

// src/graphql/typeDefs.ts
import gql from 'graphql-tag';

export const typeDefs = gql`
  type Query {
    hello: String!
  }
  # 其他类型定义...
`;

第五步：简化编译流程（可选） #

可以跳过Babel，直接用tsconfig-paths处理运行时的路径别名，减少出错环节：

1. 安装依赖：

npm install tsconfig-paths --save-dev

2. 修改启动脚本：

"scripts": {
  "build": "tsc",
  "start": "ts-node -r tsconfig-paths/register dist/App.js"
}

验证步骤 #

1. 执行npm run build重新编译
2. 检查dist目录：确认.graphql文件已复制，TS文件中的路径别名已转为正确的相对路径
3. 运行node dist/App.js，验证错误是否消失

内容的提问来源于stack exchange，提问作者곽대용