Relay 开发工作流实战:掌握 Relay Compiler 的编译、产物生成与 watch 模式

原创2026-09-22 15:21:301,915 阅读
文章标签:前端开发工具

Relay 开发工作流实战:掌握 Relay Compiler 的编译、产物生成与 watch 模式

本文聚焦 Relay(数据驱动的 React 应用框架)日常开发中贯穿始终的「编译工作流」:如何在编写 Fragment 与 Query 之前完成 Relay Compiler 的安装与配置,如何通过 yarn run relay 与 yarn run relay --watch 生成并持续更新编译产物,以及这些命令背后编译器到底做了什么。读完本文,你将具备一套可直接落地的 Relay 开发循环:改代码 → 触发编译 → 校验产物 → 进入下一轮迭代。

为什么 Relay 开发离不开「编译」这一步

与许多把 GraphQL 请求字符串留到运行时再处理的方案不同,Relay 采用提前编译(ahead-of-time compilation)的策略。在 Relay Compiler 官方指南 中明确写道:graphql 模板标签在运行时永远不会被执行,它会被 Relay Compiler 提前编译为与源码并存的生成文件(artifacts),Relay 运行时(browser 中运行的代码)依赖这些产物才能正常工作。

因此,工作流的第一步非常关键:在开始编写任何 Relay 代码之前,必须先把 Relay Compiler 安装并配置好。关于这一前置步骤的完整说明,可参考 安装与配置指南。在配置完成后,只要你以 Fragments 或 Queries 的形式编写 Relay 组件,就需要运行 Relay Compiler 来生成对应的运行时产物。

准备就绪:安装并配置 Relay Compiler

安装编译器与 bin 脚本

在项目根目录执行:

yarn add --dev relay-compiler

该包在 packages/relay-compiler/package.json 中声明了 "bin": "cli.js",即安装完成后 node_modules/.bin/relay-compiler 可执行脚本即可用;packages/relay-compiler/cli.js 是标准的 Node bin 入口,负责把命令行参数透传给真正的编译实现。

官方推荐的做法是把编译器挂到 package.json 的 scripts 中,这样后续只需一条简短命令:

"scripts": {
  "relay": "relay-compiler"
}

创建编译器配置文件

Relay Compiler 需要一个配置文件来告诉它:去哪里找源码、用哪个 GraphQL Schema、输出什么语言等。在 relay.config.js 中写入如下内容:

// relay.config.js
module.exports = {
  // Configuration options accepted by the `relay-compiler` command-line tool and `babel-plugin-relay`.
  src: "./src",
  language: "javascript", // "javascript" | "typescript" | "flow"
  schema: "./data/schema.graphql",
  excludes: ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"],
}

各核心配置项说明:

配置项 作用 说明
src 指定包含 graphql 字面量的源码目录 编译器将扫描该目录下的 .js 文件
schema 指定 GraphQL Schema 文件路径 指向 .graphql 格式的 Schema 描述文件(见下文「Schema 从哪来」)
language 产物中类型生成的语言 可选 "javascript"、"typescript"、"flow"
excludes 需要排除的 glob 路径 默认排除 node_modules、__mocks__、__generated__ 等目录

该配置同样可以写在 package.json 的 "relay" 字段中。仓库中的真实示例可参考 compiler/test-project/relay.config.json,它使用了多项目(projects)配置结构,并指定 schema 为 packages/relay-test-utils-internal/testschema.graphql、语言为 javascript。

编译器如何找到配置文件

从新版本编译器的 Rust 实现看,配置查找有固定的优先级顺序。在 compiler/crates/relay-compiler/src/config.rs 中,default_loader_sources 依次尝试:

  1. package.json 中的 "relay" 键
  2. relay.config.json
  3. relay.config.js
  4. relay.config.cjs
  5. relay.config.mjs

若完全找不到配置,编译器会报错并提示创建配置文件的正确格式(源码中保留了完整的示例报错文案):

{
  "src": "./src",
  "schema": "./path-to/schema.graphql",
  "language": "javascript"
}

Schema 从哪来

编译 Query 和 Fragment 的前提是有一份描述 GraphQL 服务端 API 的 Schema 文件(.graphql),例如官方指南中给出的 schema.graphql:

schema {
  query: Root
}

type Root {
  dictionary: [Word]
}

type Word {
  id: String!
  definition: WordDefinition
}

type WordDefinition {
  text: String
  image: String
}

这类文件通常是服务端 Schema 的本地表示,一般由服务端自动导出,不直接手工编辑。仓库中可参考 compiler/test-project/relay.config.json 所引用的 packages/relay-test-utils-internal/testschema.graphql。

日常开发循环:运行 Relay Compiler

一次性编译

在开发 Relay 组件(编写 Fragment 或 Query)后,运行:

yarn run relay

该命令会扫描 src 下的源码,找到所有 graphql 模板标签,经解析、校验、转换后生成一系列 __generated__ 目录,且这些目录与包含 graphql 标签的源文件位置一一对应(co-located)。

以官方指南中的示例为例,给定两个源文件:

  • src/Components/DictionaryComponent.js
const DictionaryWordFragment = graphql`
  fragment DictionaryComponent_word on Word {
    id
    definition {
      ...DictionaryComponent_definition
    }
  }
`

const DictionaryDefinitionFragment = graphql`
  fragment DictionaryComponent_definition on WordDefinition {
    text
    image
  }
`
  • src/Queries/DictionaryQuery.js
const DictionaryQuery = graphql`
  query DictionaryQuery {
    dictionary {
      ...DictionaryComponent_word
    }
  }
`

编译后会生成三个文件、两个 __generated__ 目录:

  • src/Components/__generated__/DictionaryComponent_word.graphql.js
  • src/Components/__generated__/DictionaryComponent_definition.graphql.js
  • src/Queries/__generated__/DictionaryQuery.graphql.js

仓库的测试项目中存在完全一致的结构:源码 compiler/test-project/src/App.js 中定义了 AppQuery 查询(内含 ...Component_node 片段展开),对应的产物文件为 compiler/test-project/src/generated/AppQuery.graphql.js 与 compiler/test-project/src/__generated__/Component_node.graphql.js。

watch 模式:边改边编译

手动跑编译很快会变得繁琐,因此编译器提供了 watch 模式:

yarn run relay --watch

开启后,编译器会持续监听源码变化,每当文件被修改或新增,就自动重新生成受影响的产物。需要特别注意的是:watch 模式依赖 watchman(Facebook 开发的跨平台文件监听工具),请确保开发机已安装。

从源码看,watch 模式的实现位于 compiler/crates/relay-compiler/src/compiler.rs 的 Compiler::watch:编译器建立 Watchman 订阅后进入一个「收到变更通知 → 合并文件变更 → 增量重建 → 重新等待」的循环。增量构建逻辑中还有一处细节:单个文件的修改有时会触发两次 Watchman 事件,因此编译器会先等待 50ms 再处理,避免重复编译(见 compiler.rs 中的注释与实现)。

如果环境中确实没有 watchman,也可以通过 --noWatchman 之类的开关回退到目录遍历方式,但那样 watch 模式将不可用——这一约束在 compiler/crates/relay-bin/src/main.rs 的 CLI 入口中有明确的报错分支。

编译产物里有什么

生成的文件是「双重产物」:

  • 运行时 artifact:帮助 Relay 运行时读写 Relay Store(Relay 的客户端数据缓存);
  • 类型定义:以 Flow 类型注释(type comments)的形式生成,帮助写出类型安全的代码。

日常开发中,你通常不需要手动 import 这些生成文件——babel-plugin-relay 会在 Babel 编译阶段把代码里的 graphql 字面量自动转换为对生成文件的 require() 调用(安装方式:yarn add --dev babel-plugin-relay graphql,然后在 .babelrc 的 plugins 中加入 "relay",并确保它排在其它插件/预设之前)。

但以下两种情况你可能需要显式引用产物:

  1. 使用生成类型(Flow / TypeScript 场景):
import type {DictionaryComponent_word} from './__generated__/DictionaryComponent_word.graphql';
  1. 跨文件复用某个操作(较少见):同一个 query / mutation / fragment 需要在多个文件中使用,可直接引入:
import DictionaryComponent_word from './__generated__/DictionaryComponent_word.graphql';

深入一层:一次编译的背后发生了什么

从新编译器的 Rust 实现(compiler/crates/relay-compiler/src/compiler.rs 的模块注释)可以清晰地看到 compile 的完整流水线:

  1. 解析:把 GraphQL 源码解析为抽象语法树(AST);
  2. 校验:对照 GraphQL 规范及 Schema 校验 AST(例如字段是否存在、类型是否匹配);
  3. 转换(transforms):对 AST 应用一系列优化与转换——这正是提前编译价值的核心:例如查询中重复的字段可以在构建阶段被合并,从而提升 GraphQL 响应处理效率;这些优化如果在运行时做代价过高;
  4. 生成输出:基于转换后的 AST 写出产物文件。

产物写盘后,编译器还会维护一份「artifact map」(产物映射),用于增量编译时精确判断哪些文件需要重建,而不是全量重编。这也是 watch 模式能够做到「改一个文件只重编相关产物」的原因。

CLI 参数速查与故障排查

编译命令的完整参数定义在 compiler/crates/relay-bin/src/main.rs,常用参数如下:

参数 作用
--watch / -w 开启 watch 模式,监听文件变化持续编译
--project / -p 只编译指定项目(多项目配置时使用),可重复传多次
--config 指定配置文件路径;不传则按上文优先级自动查找
--validate 只检查是否有待写入的变更,不写盘;有变更时以非零码退出(适合 CI)
--output 日志详细程度:debug / quiet / quiet-with-errors / verbose(默认 verbose)
--noWatchman 禁用 watchman,改用目录遍历寻找源文件(与 --watch 互斥)

常见的两类问题:

  • 「Configuration for Relay compiler not found」:说明当前目录向上找不到任何合法配置,按报错提示在项目根目录创建 relay.config.json(或 package.json 的 "relay" 字段)即可;
  • watch 模式启动失败:通常是 watchman 未安装,安装 watchman 后重试。

完整工作流小结

把以上内容串起来,一套标准的 Relay 日常开发循环是:

  1. 一次性安装并配置:yarn add --dev relay-compiler + 创建 relay.config.js + 添加 "relay": "relay-compiler" 脚本(详见 installation-and-setup.md);
  2. 启动持续编译:yarn run relay --watch;
  3. 编写/修改带 graphql 标签的组件(Fragment / Query);
  4. 编译器自动更新 __generated__ 产物,babel-plugin-relay 在构建时自动接入产物;
  5. 在浏览器中运行应用,Relay 运行时消费编译产物读写 Store。

整个循环的核心原则是:GraphQL 的一切编译工作在开发期完成,浏览器中的 Relay 运行时只负责消费高效、优化过的产物。理解了这一点,你就能更自然地驾驭 Relay 的日常开发节奏。

延伸阅读:Relay Compiler 官方指南(graphql 标签与产物生成的完整说明)、Rendering 章节(Fragment 与 Query 的编写方式,即触发编译的源码形态)。

登录后查看全文
relay