Relay 开发工作流:掌握 Relay Compiler 的安装、配置与 watch 模式
Relay 开发工作流:掌握 Relay Compiler 的安装、配置与 watch 模式
本篇技术指南围绕 Relay 官方工作流文档(website/versioned_docs/version-v15.0.0/guided-tour/workflow.md)展开,系统讲解 Relay 数据驱动 React 应用的核心开发节奏:如何在项目中安装并配置 Relay Compiler,如何用 yarn run relay 一次性编译 graphql 字面量,以及如何用 --watch 模式在编写 Fragments、Queries、Mutations 时自动增量生成编译产物。读完本文,你将掌握一套可复制、可运行、可排查的 Relay 编译工作流,并理解其背后的 AOT(Ahead-of-Time)编译原理与源码级实现。
为什么 Relay 需要 Compiler:一次理解 AOT 编译
Relay 的核心工作流始于这样一个事实:Relay 的 graphql 模板标签永远不会在运行时执行。你在 JavaScript 代码里写的 graphql 字面量,只是编译器的输入。真正在浏览器中驱动 Relay 运行时(读取/写入 Relay Store、发起网络请求)的,是编译器预先产出的那一批"编译产物"(artifacts)。
这就是文档所指出的 Relay 工作流的第一步:
Before we can get started writing Relay code, we need to make sure to setup the Relay Compiler.
Relay Compiler 会扫描 JavaScript 代码中所有的 graphql 字面量,分析其中的 Fragments、Queries、Mutations 和 Subscriptions,并生成一组被 Relay 运行时在浏览器中使用的产物文件。这种"提前编译"(Ahead-of-Time Compilation)带来了两大收益:
- 运行时更轻:Relay 运行时无需在客户端解析 GraphQL 字符串、生成查询字符串,省去了运行时的昂贵开销;
- 构建期可优化:许多优化(例如合并查询中重复的字段,提升 GraphQL 响应处理效率)可以在构建期完成,而不必等到运行时。
这些说法并非空谈——在 编译器工作流文档 中,官方明确写道:"The Relay Compiler is responsible for generating code as part of a build step which can then be referenced at runtime. By building the query ahead of time, the Relay's runtime is not responsible for generating a query string, and various optimizations can be performed on the query that could be too expensive at runtime"。在 新编译器介绍博客 中还可以看到,从 v15 起 Relay 已采用 Rust 重写的编译器实现,其二进制入口位于 compiler/crates/relay-bin/src/main.rs。
第一步:安装并设置 Relay Compiler
在开始编写任何 Relay 代码之前,先完成编译器的安装与配置。完整步骤见 安装与设置文档。
安装编译器
使用 yarn 或 npm 将 relay-compiler 作为开发依赖安装:
yarn add --dev relay-compiler
安装完成后,node_modules 中会出现 relay-compiler 这个 bin 脚本。官方建议把它包装成 package.json 的脚本,方便统一调用:
"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 文件路径 | 描述服务端 API 的 .graphql 文件 |
language |
目标语言 | "javascript" / "typescript" / "flow",决定生成的类型风格 |
excludes |
排除的 glob 模式 | 默认排除 node_modules、__mocks__、__generated__ 等目录 |
该配置也可以直接写在 package.json 的 "relay" 字段中。
从源码层面看,Relay Compiler 的配置加载逻辑支持多种配置文件来源。在 compiler/crates/relay-compiler/src/config.rs 中定义了默认的加载器顺序:
package.json中的"relay"键;relay.config.json;relay.config.js/relay.config.cjs/relay.config.mjs。
Config::search 会从当前工作目录向上逐级查找这些配置文件,而 Config::load 支持显式传入配置文件路径(扩展名必须是 .js、.cjs、.mjs 或 .json,否则报错)。仓库自带的 compiler/test-project/relay.config.json 就是一个真实的多项目配置示例,展示了 root、header(产物文件头注释)、sources(源码目录到项目的映射)以及 projects 下的 schema、language 等字段的实际用法。
配置 babel-plugin-relay
要让 Babel 把代码中的 graphql 字面量转换成对生成产物的引用,还需要安装 Babel 插件:
yarn add --dev babel-plugin-relay graphql
然后在 .babelrc 中启用:
{
"plugins": [
"relay"
]
}
注意:"relay" 插件应先于其他插件或 preset 执行,以确保 graphql 模板字面量被正确转换。若不想用 Babel 插件,也可以改用 babel-plugin-macros,即 require('babel-plugin-relay/macro')。
第二步:运行 Relay Compiler
完成设置后,编写 Relay 组件的日常动作就是"写代码 → 跑编译器"。比如当你编写 Fragments 或 Queries 时,运行:
yarn run relay
这条命令会扫描源码、解析 graphql 字面量、校验查询、执行各类 transform,并把产物写到与源码文件同级的 __generated__/ 目录中。
watch 模式:随写随编
更贴近日常开发的是 watch 模式——每当源码更新,产物自动重新生成:
yarn run relay --watch
在 watch 模式下,编译器持续监听文件变化并做增量编译,开发者无需手动反复触发。这也是 Relay 官方推荐在开发期间使用的工作方式。
从源码实现看,watch 模式依赖 graphql-watchman crate 与 Watchman 中有一条明确的校验逻辑:如果用户传入 --watch 而环境中没有 Watchman,编译器会直接报错退出:
Cannot run relay in watch mode if
watchmanis not available. Install watchman or remove the--watchflag.
而文件来源(FileSource)的选择逻辑在 compiler/crates/relay-compiler/src/config.rs 中定义了四种:Watchman(默认,基于 Watchman 的增量文件源)、WalkDir(目录遍历,配合 --noWatchman)、External(外部传入变更文件列表)与 Test(测试用)。--noWatchman 选项与 watch 模式互斥,因为纯目录遍历无法高效驱动持续的增量监听。
编译器做了什么:从 graphql 字面量到 __generated__ 产物
理解工作流,还需要知道产物长什么样。以 编译器文档 的示例为例,给定如下 fragment:
graphql`
fragment MyComponent on Type {
field
}
`
运行编译器后,会在 ./__generated__/MyComponent.graphql.js 生成产物文件,其中既包含运行时产物(帮助读写 Relay Store 的代码),也包含 Flow 类型(帮助编写类型安全代码)。
具体而言,编译一个项目需要两样东西:
- GraphQL Schema 文件(
.graphql):描述服务端 API,通常是服务端真实 schema 的本地表示,例如:
schema {
query: Root
}
type Root {
dictionary: [Word]
}
type Word {
id: String!
definition: WordDefinition
}
type WordDefinition {
text: String
image: String
}
- 使用
graphql标签的源码目录(即配置中的./src)。
运行 yarn run relay 后,编译器会在与源码文件同级的目录下创建 __generated__ 目录。例如给定 src/Components/DictionaryComponent.js(含两个 fragment)和 src/Queries/DictionaryQuery.js(含一个 query),将产出:
src/Components/__generated__/DictionaryComponent_word.graphql.jssrc/Components/__generated__/DictionaryComponent_definition.graphql.jssrc/Queries/__generated__/DictionaryQuery.graphql.js
如何引用生成的定义
日常开发中你通常不需要手动 import 生成产物——babel-plugin-relay 会自动把 graphql 字面量转成对生成文件的 require() 调用。但有三种情况需要显式引用:
- 引入生成的 Flow 类型(编译器会自动为产物生成类型注释):
import type {DictionaryComponent_word} from './__generated__/DictionaryComponent_word.graphql';
- 跨文件复用某个 query / mutation / fragment / subscription 时直接导入产物值:
import DictionaryComponent_word from './__generated__/DictionaryComponent_word.graphql';
更完整的 CLI 选项:从源码看编译器能力边界
除了 --watch,新版 Rust 编译器的命令行还提供了更多与工作流相关的选项,全部定义在 compiler/crates/relay-bin/src/main.rs 的 CompileCommand 中:
| 选项 | 作用 |
|---|---|
-w, --watch |
编译并持续监听文件变化(需要 Watchman) |
-p, --project |
只编译指定项目,可多次传入;多项目配置下未指定的项目会被禁用 |
--config |
显式指定配置文件路径;否则从当前目录向上搜索 |
--noWatchman |
禁用 Watchman,改用目录遍历;与 --watch 互斥 |
--output |
日志详细程度:debug / quiet / quiet-with-errors / verbose(默认 verbose) |
--validate |
只检查是否有待写入的变更并以非零码退出,不实际写盘(适合 CI) |
--repersist |
即使查询文本未变化也重新执行持久化器 |
--daemon(Unix) |
将构建交给后台编译守护进程,复用内存态以消除每次构建的启动开销;与 --watch、--validate、--repersist 及内联配置参数互斥 |
CLI 还内置了若干子命令:lsp(启动语言服务器,供 IDE 使用)、config-json-schema(打印配置的 JSON Schema)、codemod(应用代码转换)、experimental-regenerate-sub-schema 与 experimental-compare-document-ir(实验性 schema 提取与 IR 对比),以及 Unix 下的 server(守护进程管理)。这些能力让 Relay 编译器不仅是构建工具,也构成了 IDE 支持与自动化基础设施的一部分——仓库中的 relay-lsp crate 即对应 lsp 子命令。
值得注意的是,CLI 已不再支持通过命令行参数直接传 --src / --schema / --artifactDirectory:在 main.rs 中,如果检测到这些内联配置,会提示改用 relay.config.json 或 package.json 的 "relay" 段。
开发环境要求与工作流补充
为了让整套工作流在你的项目里顺畅运转,还有几点环境层面的要求值得留意:
- Node 运行时与浏览器 polyfill:Relay 的 npm 包使用 ES5 语法以兼容尽可能多的浏览器,但运行时依赖现代 JavaScript 全局对象(
Map、Set、Promise、Object.assign)。如需支持旧浏览器,建议引入core-js等 polyfill,例如:
require('core-js/es6/map');
require('core-js/es6/set');
require('core-js/es6/promise');
require('core-js/es6/object');
require('./myRelayApplication');
- Watchman:watch 模式的前置依赖,负责高效监听文件系统变化。
__generated__目录的产物:建议将生成产物提交进版本控制(Relay 官方默认产物会写盘),且excludes中通常包含__generated__,避免编译器把自身产物当作源码二次扫描。
总结:一套完整的 Relay 迭代循环
Relay 的开发工作流可以浓缩为一条闭环:
- 安装
relay-compiler+babel-plugin-relay,创建relay.config.js(src、schema、language); - 在组件中编写
graphql字面量(Fragment / Query / Mutation / Subscription); - 运行
yarn run relay生成产物,或yarn run relay --watch让产物随代码变更自动更新; - Babel 插件把
graphql字面量替换为对__generated__/*.graphql.js的引用; - 运行时借助产物完成数据读取、写入与查询执行。
这套工作流正是"数据驱动 React 应用"(Relay 的定位)得以落地的基础:把 GraphQL 的能力前置到构建期,换来运行时的轻量与可靠。更多细节可继续查阅 Relay Compiler 文档、安装与设置文档,或直接在 compiler 目录 中阅读编译器的 Rust 实现与测试用例。