Relay 开发工作流实战:掌握 Relay Compiler 的编译、产物生成与 watch 模式
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 依次尝试:
package.json中的"relay"键relay.config.jsonrelay.config.jsrelay.config.cjsrelay.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.jssrc/Components/__generated__/DictionaryComponent_definition.graphql.jssrc/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",并确保它排在其它插件/预设之前)。
但以下两种情况你可能需要显式引用产物:
- 使用生成类型(Flow / TypeScript 场景):
import type {DictionaryComponent_word} from './__generated__/DictionaryComponent_word.graphql';
- 跨文件复用某个操作(较少见):同一个 query / mutation / fragment 需要在多个文件中使用,可直接引入:
import DictionaryComponent_word from './__generated__/DictionaryComponent_word.graphql';
深入一层:一次编译的背后发生了什么
从新编译器的 Rust 实现(compiler/crates/relay-compiler/src/compiler.rs 的模块注释)可以清晰地看到 compile 的完整流水线:
- 解析:把 GraphQL 源码解析为抽象语法树(AST);
- 校验:对照 GraphQL 规范及 Schema 校验 AST(例如字段是否存在、类型是否匹配);
- 转换(transforms):对 AST 应用一系列优化与转换——这正是提前编译价值的核心:例如查询中重复的字段可以在构建阶段被合并,从而提升 GraphQL 响应处理效率;这些优化如果在运行时做代价过高;
- 生成输出:基于转换后的 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 日常开发循环是:
- 一次性安装并配置:
yarn add --dev relay-compiler+ 创建relay.config.js+ 添加"relay": "relay-compiler"脚本(详见 installation-and-setup.md); - 启动持续编译:
yarn run relay --watch; - 编写/修改带
graphql标签的组件(Fragment / Query); - 编译器自动更新
__generated__产物,babel-plugin-relay在构建时自动接入产物; - 在浏览器中运行应用,Relay 运行时消费编译产物读写 Store。
整个循环的核心原则是:GraphQL 的一切编译工作在开发期完成,浏览器中的 Relay 运行时只负责消费高效、优化过的产物。理解了这一点,你就能更自然地驾驭 Relay 的日常开发节奏。
延伸阅读:Relay Compiler 官方指南(
graphql标签与产物生成的完整说明)、Rendering 章节(Fragment 与 Query 的编写方式,即触发编译的源码形态)。