GraphQL

借助 WebStorm，您可以使用支持 GraphQL 语言的 GraphQL 插件。可用的功能包括：

完整支持 GraphQL 规范语言，包括 Schema Definition Language (SDL)。
基于架构的代码补全、错误高亮和文档查看。
语法高亮、代码格式化、代码折叠、注释器与括号匹配功能。
即时检测本地 schema。可通过内省轻松获取远程 schema。您可以对 GraphQL 端点进行内省，使用 GraphQL 类型系统定义语言生成 schema 声明文件。
通过可配置的项目范围或 graphql-config 文件支持 multi-schema 项目。通过 graphql-config 文件配置 schema 的发现方式，支持 multi-schema 项目。
内置支持 Apollo GraphQL 与 Relay 项目：在 JavaScript 与 TypeScript 中， graphql 与 gql 标签模板字符串将自动识别为 GraphQL。
使用变量在可配置端点上执行查询，包括对自定义请求头和环境变量的支持。
查找用法与跳转到声明，适用于类型、字段及片段。
使用结构视图浏览 GraphQL 文件。
可从 shell、 .env 文件加载变量，或通过配置文件手动设置。
内置 Relay、 Federation 与 Apollo Kotlin 类型定义（需在设置 | 语言与框架 | GraphQL 中启用）。

GraphQL 通过专用的 GraphQL 插件提供支持，该插件可从 JetBrains Marketplace 获取。

安装 GraphQL 插件

按下 Ctrl+Alt+S 打开设置，然后选择设置 | 插件。
在 Marketplace 选项卡中，在搜索框内开始输入 graph ，从列表中选择 GraphQL ，然后单击安装。

配置应用以使用 GraphQL

配置如何发现 schema 类型非常重要。根据 schema 类型的信息，WebStorm 提供代码补全与错误高亮等编码辅助功能。

schema 及其类型通过 GraphQL 类型系统定义语言声明，也称为 GraphQL Schema Definition Language （常缩写为 SDL）。如果您在 SDL 中编写 schema，插件将提供以下功能：

在定义字段、参数、实现接口等时为类型提供补全。
对 schema 错误进行高亮，例如未知类型、类型误用、接口实现缺少字段等。
在 SDL 中查找用法与重构（如重命名），相关查询、变更等将随之更新。

对于单架构项目，会自动发现架构类型，无需您进行任何额外配置。 WebStorm 会处理 .graphql 文件，在项目文件作用域中查找类型定义，并将检测到的类型定义添加到单例类型注册表中。项目文件作用域中的注入 GraphQL 字符串会针对所有 JavaScript 文件类型进行处理 ——.js、 .jsx、 .ts、 .tsx、 .html 和基于 html 的文件（例如 .vue）。

对于多架构项目，应为每个架构配置一个作用域。架构专属的作用域可确保每个类型仅声明一次，并且只在一个 GraphQL 类型注册表中被读取，这可以防止验证错误。此外，这些作用域还可防止无冲突的类型出现在补全项中，并确保验证只识别属于当前架构的类型。

详细信息请参阅 GraphQL 配置简介。

基本配置

在项目工具窗口中，将光标放置在要创建简单配置文件的文件夹上，然后选择新建 | GraphQL 配置。

WebStorm 会创建一个文件 graphql.config.yml 并在编辑器中打开该文件：

                        schema: schema.graphql
                        documents: '**/*.graphql'

此配置文件表示架构定义应位于 schema .graphql 文件中。 documents 键使用 glob 模式定义，将包含当前目录或嵌套目录中的任意 GraphQL 操作。术语 operation 仅指 GraphQL 查询和片段，不包括类型定义。

请注意，路径是相对于配置目录指定的，除非明确定义为绝对路径。因此，您无需在前面添加前缀 ./。只使用 schema.graphql 即可。 glob 模式也适用相同原则。

node_modules 配置

要使用 node_modules 文件夹中的架构，请创建一个 GraphQL 配置文件（例如 graphql.config.yml ），并如下指定架构路径：

schema: node_modules/@octokit/graphql-schema/schema.graphql

复合模式

GraphQL 配置还可以通过指定架构文件列表，将多个模块化架构组装为一个 GraphQL 架构对象：

                schema:
                  - ./foo.graphql
                  - ./bar.graphql
                  - ./baz.graphql
            
   

或者，您也可以使用 glob 模式查找并包含架构片段：

                schema: ./*.graphql # includes every GraphQL file in current directory
                # OR
                schema: ./**/*.graphql # includes GraphQL files recursively
            
   

GraphQL 配置会查找指定的文件，读取这些文件并将其合并为一个 GraphQL 架构对象。

远程模式

如果您有 GraphQL 端点但尚无本地架构文件，您可以定义一个或多个端点并发起一次自省查询。这将从服务器加载架构，转换为 GraphQL 文件，并将其保存到 IDE 的缓存目录中。

具体可根据是否需要为端点执行其他配置，将其定义为字符串或包含头信息等附加键的对象。

schema: https://my.api.com/graphql

                  schema:
                    - https://my.api.com/one/graphql
                    - https://my.api.com/two/graphql
            
   

                  schema:
                    - https://my.api.com/one/graphql:
                        headers:
                          Authorization: Bearer ${TOKEN}
            
   

本地自省模式

要将自省结果以本地方式存储，请像传统配置格式中一样配置端点。在 endpoints 扩展中定义一个或多个端点，然后发起一次自省查询。文件会保存在对应 schema 部分的第一个路径，例如下方示例中的 local.graphql 文件。

                schema: local.graphql
                extensions:
                  endpoints:
                    One:
                      url: https://my.api.com/one/graphql
                      headers:
                        Authorization: bearer ${TOKEN}
                    Two:
                      url: https://my.api.com/two/graphql
            
   

高级配置

要更精细地控制哪些文件应包含在架构中，请使用可选的 include 和 exclude 键。首先，会检查候选文件是否被排除。如果未排除该文件，其路径将与 include 模式进行匹配。

在下方示例中， schema.graphql 和 src 目录中的所有文件（不包含 __tests__ 目录中的文件）将包含在该项目中。

                schema: schema.graphql
                exclude: 'src/**/__tests__/**'
                include: src/**
            
   

多个项目

按项目配置

config 文件定义了一个 GraphQL "module" 根，就像 package .json 或类似文件一样。即使 config 文件为空，其所在目录及子目录中的所有文件也会使用与该配置关联的架构。

因此，分离不同架构的最简单方式是在每个子目录中创建一个配置文件（前提是它们完全独立，这通常适用于 monorepo 项目）。通过这种方式，每个 config 文件的位置都为各自的子树创建了独立作用域。

单一配置

如果您更倾向于只使用一个配置文件，也可以在同一文件中指定多个项目。

                        - project root/
                            - .graphql.config.yml <-----
                            - frontend (schema one)/
                                - schema files and graphql aware components
                            - backend (schema two)/
                                - schema files and graphql aware components
                            - queries/
                    
     

此类情形下的配置方式如下：

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    
     

文件会按项目在配置中的定义顺序进行匹配。因此，如果某个文件同时匹配多个项目，将选择第一个项目。

如果未为某个项目定义 include 或 exclude 键，则 GraphQL 操作将采用非严格方式匹配。这意味着，如果某个查询或片段未明确匹配到任何项目，该文件将关联到第一个未定义 include 或 exclude 的项目。在上面的示例中，除了 backend 和 frontend 之外，还有一个名为 queries 的额外根目录。如果 queries 包含一些不匹配任何提供模式的 GraphQL 文档，则第一个项目 frontend 将关联这些查询。

为实现此目的，您可以将 exclude 模式添加到 frontend 项目配置中。这将把 queries 文件夹中的文件与 backend 项目关联起来。

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                            exclude: queries/**  # <--- will enable strict matching for that project
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    
     

这不适用于类型定义，如前所述。 WebStorm 仅使用严格匹配 schema 或 include 键的文件中的类型定义。

配置文件

WebStorm 能识别以下格式的配置文件：

graphql.config.json
graphql.config.js
graphql.config.cjs
graphql.config.mjs
graphql.config.ts
graphql.config.mts
graphql.config.cts
graphql.config.yaml
graphql.config.yml
.graphqlrc （YAML 和 JSON）
.graphqlrc.json
.graphqlrc.yaml
.graphqlrc.yml
.graphqlrc.js
.graphqlrc.mjs
.graphqlrc.ts
.graphqlrc.mts
.graphqlrc.cts

YAML

请确保在设置 | 插件页面的已安装选项卡中启用了 YAML 捆绑插件，如安装插件中所述。

JavaScript

请确保您的计算机上安装了 Node.js。 Node.js 用于下载 JavaScript 配置文件。
WebStorm 不会转译配置文件，因此请确保它们使用适用于 Node.js 的模块系统编写。在下面的示例中，使用的是 module.exports 语法，而非 export default。
module.exports = { schema: 'https://localhost:8000' }
要在配置中使用 ESM ，请将 "type": "module" 添加到 package.json 文件中。

TypeScript

请确保您的计算机上安装了 Node.js。 Node.js 用于下载 TypeScript 配置文件。
要加载 TypeScript 配置，请在内置终端工具窗口 Alt+F12 中，键入以下命令之一来下载并安装 ts-node 包：
- npm install --save-dev ts-node 可将该包安装到您的项目中。
- npm install --g ts-node 可将该包全局安装到您的计算机
了解更多内容，请参阅 Typestrong ts-node。
要在项目中使用 ESM 模块：
- 请在 package .json 文件中将 ESM 模块配置为 "type": "module"。
- 为 ts-node 设置 ESM 加载器，请将以下内容添加到 tsconfig.json 文件中：
  { "compilerOptions": { // or ES2015, ES2020 "module": "ESNext" }, "ts-node": { "esm": true } }
了解更多内容，请参阅 Native ECMAScript modules。

迁移

如果您仍在使用旧版配置文件，例如 .graphqlconfig ，强烈建议您将其转换为首选的现代格式，例如 YAML，因为它最为方便。 WebStorm 集成了一个自动转换工具，当您打开旧版文件时会在编辑器上方显示通知面板。只需单击通知面板中的迁移，即可自动更新配置键和环境变量语法。

建议将曾用于配置复合 schema 的现有 includes 模式迁移至新的 schema 键。请注意，环境变量现在具有不同的语法，例如支持指定默认值。

旧版配置

如果您仍希望使用旧版配置格式，请务必在 includes 属性中明确指定 schema 文件的路径。否则，仅会使用来自 schemaPath 的类型来构建 schema。

                {
                      "schemaPath": "schema.graphql",
                      "includes": [
                          "Types1.graphql",
                          "types/**/*.graphql",
                          "src/files/*.{graphql,js,ts}",
                          "everything/inside/**"
                      ],
                      "excludes": [
                          "types/excluded/**"
                      ]
                  }
            
   

环境变量

您可以在配置文件中使用环境变量来指定 schema 路径、URL 或 header 值。在配置文件中使用环境变量的语法如下：

                ${VARIABLE_NAME}
                ${VARIABLE_WITH_DEFAULT:./some/default/file.graphql}
                ${VARIABLE_QUOTED:"http://localhost:4000/graphql"}
            
   

您可以从环境变量中加载定义，可选提供回退值。

schema: ${SCHEMA_FILE:./schema.json}

如果要定义一个备用端点，可能需要将值用引号括起来。

schema: ${SCHEMA_ENDPOINT:"http://localhost:4000/graphql"}

.env 文件

有多种方法可以提供环境变量。最推荐的方法是创建一个包含变量值的专用文件。为避免泄露凭据，请勿提交此文件。

以下文件名按优先级顺序支持，从高到低：

.env.local
.env.development.local
.env.development
.env.dev.local
.env.dev
.env

WebStorm 会从包含相应配置文件的目录开始，逐级向上搜索指定的文件，直到项目根目录。

在此类文件中，环境变量以用 = 符号分隔的简单键值对形式表示。值可以选择性地用引号括起来。

                    S3_BUCKET="YOURS3BUCKET"
                    SECRET_KEY=YOURSECRETKEYGOESHERE # comment
                    SECRET_HASH="something-with-a-#-hash"
                
    

手动配置

要使用 .env 文件，请通过以下任一方式为每个配置文件手动提供环境变量：

要在配置文件中编辑 GraphQL 环境变量，请在编辑器中打开该文件，右键点击任意位置以打开上下文菜单，然后选择编辑 GraphQL 环境变量。这将打开一个模态对话框，您可以在其中为文件中的每个环境变量提供值。
打开任意 GraphQL 文件并单击工具栏。此对话框将自动查找匹配的配置文件。
否则，将仅在首次执行 introspection 查询或 GraphQL 请求时请求缺失的变量。

系统

如果在 .env 文件中找不到变量，也未手动设置，WebStorm 会尝试从您的系统环境中获取变量。

框架

Gatsby

在项目根目录下创建一个 graphql.config.js ，其内容如下：

module.exports = require("./.cache/typegen/graphql.config.json")

自省

为了提供解析、补全和验证功能，WebStorm 需要一个 schema。这可以通过执行一次 introspection 查询实现，需事先完成相关配置。

运行自省查询

打开 YAML 或 JSON 配置文件，并点击边距中的。这将执行一次 introspection 查询，并根据配置将文件保存到本地，在 IDE 缓存或项目源中。
打开一个 schema 文件，并从工具栏中选择运行 Introspection 查询。
在 GraphQL 工具窗口中，右键单击某个端点，并在上下文菜单中选择从端点获取 GraphQL 架构。
要在编辑器中查看 introspection 文件的 schema 结构，请在工具栏中使用打开 Introspection 架构操作。这将为所选端点打开一个文件。
如果您不希望每次查询后都打开 introspection 结果文件，请按 Ctrl+Alt+S 打开设置，选择语言与框架 | GraphQL ，然后取消选中打开包含 Introspection 结果的编辑器复选框。

重新运行最新自省

如果您的 schema 经常变更，而您反复针对同一个端点运行相同的 introspection 操作，则可能更方便使用重新运行 Introspection 查询操作。请注意，该选项仅在您已经执行过 introspection 查询之后才会可用。

按下 Ctrl+Shift+A 打开操作选项卡中的任意位置搜索弹窗，输入 Rerun Introspection... ，然后从列表中选择重新运行 Introspection 查询。了解更多信息，请参阅搜索操作。
若要为此操作分配快捷键，请按 Alt+Enter 并在打开的对话框中指定按键。详细信息请参阅添加键盘快捷键。

检测服务器功能

服务器功能是根据 introspection 查询动态确定的，该查询返回 __Type、 __Field、 __Directive 和 __InputValue 字段的结构。

query IntrospectionCapabilitiesQuery {
  __schema {
    types {
      name
      fields {
        name
        args {
          name
        }
      }
    }
  }
}
            
   

上述查询将返回以下 schema 之一：

    type Query {
        id: ID
        name(arg: String @deprecated(reason: "Deprecated")): String
        email(filter: FilterArgs @deprecated): String
    }

    input SomeParams {
        id: ID = "<new>" @deprecated(reason: "SomeParams_id")
        name: String = "User123" @deprecated
    }

    directive @customDirective(arg: String @deprecated(reason: "directive_arg")) repeatable on QUERY

     

    type Query {
        id: ID
        name(arg: String): String
        email(filter: FilterArgs): String
    }

    input SomeParams {
        id: ID
        name: String
    }

    directive @customDirective(arg: String) on QUERY

     

按下 Ctrl+Alt+S 打开设置，然后选择高级设置。
在架构功能检测模式列表中，选择以下选项之一：
- 自适应 — 在此模式下，WebStorm 会运行一个额外的预查询，从 GraphQL 服务器请求实际可用的功能集合。
  自适应模式是默认选中的。
- 最新 — 选择此模式可在不运行预查询和检测可用功能的情况下，为现代 GraphQL 服务器启用所有默认功能。
- 旧版 — 选择此模式可在不运行预查询和检测可用功能的情况下，禁用旧 GraphQL 实现中的所有默认功能。
为提高对不兼容端点的兼容性，请选中在 Introspection 查询中跳过默认值复选框。其副作用是 schema 中将移除默认值信息。
默认情况下，该复选框未选中。
默认情况下，introspection 结果中会包含空类型。如需跳过空类型，请取消选中在 Introspection 结果中包含空类型复选框。

查询

要直接从编辑器中执行查询，将光标置于查询定义上，然后点击工具栏上的执行 GraphQL 或按下 Ctrl+Enter。查询将会发送到工具栏中所选的端点。
如果您的查询使用了变量，请点击工具栏上的打开专用变量编辑器，然后使用 JSON 格式提供变量。
或者，创建一个 GraphQL scratch 文件，并用作发送查询的测试平台。在 GraphQL 工具窗口中，双击端点节点并选择新建 GraphQL 草稿文件。

临时文件

如果 GraphQL scratch 文件的首行注释包含符合 # config=<path>[!<optionalProjectName>] 模式的字符串，将会使用指定的配置和项目进行解析与类型验证。符合此模式的注释被认为是有效的：

                # config=/user/local/project/.graphqlrc.yml
                # config=/user/local/project/.graphqlrc.yml!backend

工具栏

每个 GraphQL 文件都有一个工具栏，包含最常用的操作。

	打开配置文件	打开相应的配置文件，如若不存在则创建一个新文件。
编辑环境变量		这将打开一个对话框，用于为在关联配置文件中定义的环境变量提供值。
	切换变量编辑器	这将打开一个编辑器窗口，您可以在其中以 JSON 格式提供查询变量。
端点列表		配置文件中定义了一组已知的 URL，您可以使用它选择查询发送的目标 URL，或获取内省信息。
	执行 GraphQL	从下方编辑器执行所选 GraphQL 查询。
	执行内省查询	此操作将刷新从所选端点内省的 schema。
	打开内省 schema	该命令将打开与所选端点对应的本地文件。

工具窗口

GraphQL 工具窗口概览您的 GraphQL 项目。可以查看验证错误、执行内省查询、创建 scratch 等。

架构与项目结构选项卡概览检测到的配置文件及其关联的 GraphQL schema。该树视图中可对多个节点执行以下有用操作。

架构发现摘要－要搜索各项目中发现的类型，双击相应节点。这将打开一个对话窗口，您可以在其中搜索所有类型并导航到定义位置。
架构错误－单击错误节点即可跳转到错误源。
端点－右键点击某个端点以执行内省查询，或创建一个与所选配置文件和项目关联的 Scratch 文件。

工具窗口工具栏

GraphQL 工具窗口左侧的工具栏提供以下便捷操作：

	添加 schema 配置	在所选目录中创建配置文件。或者，您也可以在项目工具窗口中创建配置文件，如上述基本配置所述。
	编辑所选架构配置	在工具窗口中为所选节点打开配置文件。
	重新启动架构发现	此操作将清除所有已加载的架构，并从头开始启动发现过程。当缓存数据导致问题时，该操作可能会很有用。

注入

带标签的模板字符串

WebStorm 支持 graphql、 gql、 Relay.QL 和 Apollo.gql 标签。

const QUERY = gql``;

IntelliJ 基于注释的默认注入

                // language=GraphQL
                const QUERY = `query { field }`;

C 风格注释

const QUERY = /* GraphQL */ `query { field }`;

GraphQL 注释

                const QUERY = `
                    #graphql

                    query { field }
            `;

最后修改日期： 2025年 9月 26日