React/Relay Modern/GraphQL项目初始化遇Babel配置问题求助

我之前在create-react-app里集成Relay的时候也踩过一模一样的坑，不管是TS还是JS模式都出过这个问题，核心原因基本都是Babel配置没跟上Relay的要求，或者GraphQL查询的写法不符合它的静态分析规则。给你梳理几个关键排查点和解决方法：

1. 先搞定Relay的Babel插件配置 #

Relay必须依赖babel-plugin-relay来转译GraphQL查询，但create-react-app默认的Babel配置里没有这个插件。你得手动补上：

• 先安装依赖：

  npm install --save-dev babel-plugin-relay
  # 用yarn的话就是
  yarn add --dev babel-plugin-relay
  

• 接下来配置Babel：如果不想用npm run eject弹出配置（毕竟弹出后不好维护），推荐用react-app-rewired来修改配置。根目录新建config-overrides.js，写下面的内容：

  module.exports = function override(config, env) {
    config.module.rules.forEach(rule => {
      if (rule.oneOf) {
        rule.oneOf.unshift({
          test: /\.(js|mjs|jsx|ts|tsx)$/,
          exclude: /node_modules/,
          loader: require.resolve('babel-loader'),
          options: {
            plugins: [require.resolve('babel-plugin-relay')],
            cacheDirectory: true,
          },
        });
      }
    });
    return config;
  };
  

  然后把package.json里的启动命令改成react-app-rewired start，构建和测试命令也对应换成react-app-rewired build、react-app-rewired test。

2. 严格按Relay要求写GraphQL查询 #

错误提示里说的“严格以graphql的形式使用”，重点注意两个点：

• 必须用Relay导出的graphql标签，别用其他库的：

  import { graphql } from 'react-relay';
  

• 不能把查询字符串存在变量里再传入标签，必须直接把查询写在标签模板里：
  ❌ 错误写法：

  const myQuery = `query UserQuery { user { id name } }`;
  graphql(myQuery);
  

  ✅ 正确写法：

  graphql`
    query UserQuery {
      user {
        id
        name
      }
    }
  `;
  

  Relay的Babel插件要静态分析标签里的内容，动态传字符串它根本识别不了。

3. 确认Relay初始化的全流程都走完了 #

别漏了Relay的核心初始化步骤：

• 确保你已经有schema.graphql文件，并且放在了项目里的正确位置
• 配置了relay.config.js（或者.relayrc），指定schema路径和生成文件的输出目录
• 每次写/改GraphQL查询后，都要运行relay-compiler生成对应的文件：

  npx relay-compiler --src ./src --schema ./schema.graphql
  

  没运行这个命令的话，Relay根本认不出你的查询，自然会报错。

4. TypeScript模式的额外注意点 #

如果是TS项目，还要补一下类型依赖和配置：

• 安装类型包：

  npm install --save-dev @types/react-relay @types/relay-runtime
  

• 检查tsconfig.json里是否开启了esModuleInterop和allowSyntheticDefaultImports，这俩配置能避免很多TS和Relay兼容的问题。

我当时就是一开始没配置react-app-rewired的Babel插件，导致Relay的GraphQL标签没被转译，直接触发了和你一样的错误。按上面的步骤排查下来，应该能解决问题。

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