Relay 开发工作流:掌握 Relay Compiler 的安装、配置与 watch 模式

原创2026-09-21 20:55:241,948 阅读
文章标签:前端开发工具

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 watchman is not available. Install watchman or remove the --watch flag.

而文件来源(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 类型(帮助编写类型安全代码)。

具体而言,编译一个项目需要两样东西:

  1. GraphQL Schema 文件(.graphql):描述服务端 API,通常是服务端真实 schema 的本地表示,例如:
schema {
  query: Root
}

type Root {
  dictionary: [Word]
}

type Word {
  id: String!
  definition: WordDefinition
}

type WordDefinition {
  text: String
  image: String
}
  1. 使用 graphql 标签的源码目录(即配置中的 ./src)。

运行 yarn run relay 后,编译器会在与源码文件同级的目录下创建 __generated__ 目录。例如给定 src/Components/DictionaryComponent.js(含两个 fragment)和 src/Queries/DictionaryQuery.js(含一个 query),将产出:

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

如何引用生成的定义

日常开发中你通常不需要手动 import 生成产物——babel-plugin-relay 会自动把 graphql 字面量转成对生成文件的 require() 调用。但有三种情况需要显式引用:

  1. 引入生成的 Flow 类型(编译器会自动为产物生成类型注释):
import type {DictionaryComponent_word} from './__generated__/DictionaryComponent_word.graphql';
  1. 跨文件复用某个 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 的开发工作流可以浓缩为一条闭环:

  1. 安装 relay-compiler + babel-plugin-relay,创建 relay.config.js(src、schema、language);
  2. 在组件中编写 graphql 字面量(Fragment / Query / Mutation / Subscription);
  3. 运行 yarn run relay 生成产物,或 yarn run relay --watch 让产物随代码变更自动更新;
  4. Babel 插件把 graphql 字面量替换为对 __generated__/*.graphql.js 的引用;
  5. 运行时借助产物完成数据读取、写入与查询执行。

这套工作流正是"数据驱动 React 应用"(Relay 的定位)得以落地的基础:把 GraphQL 的能力前置到构建期,换来运行时的轻量与可靠。更多细节可继续查阅 Relay Compiler 文档、安装与设置文档,或直接在 compiler 目录 中阅读编译器的 Rust 实现与测试用例。

登录后查看全文
relay