API 参考：着陆页面插件

本API参考文档介绍了内置插件，它们将一个登录页面添加到Apollo Server's base URL，允许访客通过浏览器与服务器进行交互。

这包括以下插件的插件：

Apollo Server的默认登录页面为非生产环境（ApolloServerPluginLandingPageLocalDefault）
生产环境默认登录页面为生产（ApolloServerPluginLandingPageProductionDefault）
使用 GraphQL Playground 作为登录页面（ApolloServerPluginLandingPageGraphQLPlayground）
完全禁用登录页面

这些插件通过实现 renderLandingPage 插件事件来工作，只要浏览器包含 accept: text/html 标头，就会提供HTML页面。除此之外，你还可以创建一个自定义插件来渲染自定义登录页面

默认的非生产环境着陆页面

在非生产环境中，Apollo Server 4的着陆页面是Apollo Sandbox的嵌入式版本（默认在https://127.0.0.1:4000提供）：

此着陆页面设计用于本地开发，其中NODE_ENV未设置为生产。

Apollo Sandbox是专门用于本地开发的Apollo Studio的一种模式，无需Apollo账户。Sandbox包含Apollo Studio Explorer，这是一个功能强大的网络IDE，允许您针对您的服务器（或其他任何可访问的服务器）进行操作。

选项

名称 / 类型	描述
`版本` `string`	默认情况下，此插件使用发布到Apollo CDN的着陆页的最新版本。如果您想固定当前版本，可以在此指定。当前最新版本可在此链接获取。
`页脚` `boolean`	如果您没有使用嵌入式Apollo Sandbox（即您正在使用`{embed: false}`），则着陆页面显示一个页脚，其中包含指向文档的链接，说明如何配置它。要删除此页脚，请传递`footer: false`。
`文档` `string`	A GraphQL 文档（例如，查询或突变）在加载时填充到“Studio沙盒资源管理器”的编辑器中。如果您省略此信息，资源管理器初始加载将基于您的模式的一个示例查询。
`变量` `Record<string, any>`	包含初始变量值，以便在加载时填充到资源管理器中。如果提供了这些变量，它们应应用于您在`document`中提供的初始查询
`标题` `Record<string, string>`	包含初始HTTP标题值，以便在加载时填充到资源管理器中。
`collectionId` & `operationId` `string`	加载时在沙盒中填充的集合ID与操作ID的搭配。您可以通过在Studio中单击图中该操作旁边的...菜单并选择查看操作详情，从已注册的图中找到这些值。
`includeCookies` `boolean`	如果`true`，则内嵌的Apollo Studio资源管理器会在其向服务器发出的GraphQL请求中包含Cookies。默认值为`false`，除非用户在资源管理器UI中更改此设置。如果您省略此设置，资源管理器会将`includeCookies`默认设置为`false`。
`embed` `boolean \| ApolloServerPluginEmbedded` `LandingPageLocalConfigOptions`	如果设置为`true`或选项对象，Apollo服务器着陆页将在其GraphQL端点URL渲染内嵌版Apollo沙盒。Apollo沙盒，这是默认行为。如果您将此选项设置为`false`，则服务器的着陆页将是一个 splash 页，其中包含可复制命令行代码片段，显示如何通过`curl`运行操作，以及Apollo沙盒链接。

`embed` 选项

这是在您传递给ApolloServerPluginLandingPageLocalDefault的embed选项中可以包含的字段：

名称 / 类型	描述
`runTelemetry` `boolean`	如果设置为`false`，则Apollo服务器渲染的内嵌资源管理器不会初始化错误或事件跟踪。
`initialState` `Object`	包含与内嵌资源管理器页面加载时视觉状态相关的附加显示选项的对象。对于支持的子字段，请查看`initialState` 选项。
`endpointIsEditable` `boolean`	默认情况下，嵌入式沙盒有一个可由用户编辑的URL输入框。将 `endpointIsEditable` 设置为 `false` 以防止您的 Apollo Server 实例用户更改端点URL。

`initialState` 选项

这些是您可以在传递到 embed 下的 ApolloServerPluginLandingPageLocalDefault 的 initialState 选项中包含的字段：

名称 / 类型	描述
`pollForSchemaUpdates` `boolean`	如果为 `true`，嵌入式沙盒将定期轮询您的 `initialEndpoint` 以获取模式更新。默认值是 `true`。
`sharedHeaders` `Record<string, string>`	应用于嵌入式沙盒执行的所有操作的自定义头部。用户可以禁用这些头部的应用，但不能修改它们的值。嵌入式沙盒始终将其头部包含在内省查询到您的 `initialEndpoint`。示例 initialState: { sharedHeaders: { authorization: "Bearer abc123"; } }

默认生产 landing 页面

该 ApolloServerPluginLandingPageProductionDefault 显示了一个简约的 landing 页面：

此 landing 页面用于生产。它提供了一个可复制的命令行代码片段，显示如何运行服务器上的 operations。默认情况下，唯一的 Apollo 参考是一个底部，解释如何自定义页面。您还可以配置它添加一个链接查询您的 graph。

选项

名称 / 类型	描述
`版本` `string`	默认情况下，此插件使用发布到Apollo CDN的着陆页的最新版本。如果您想固定当前版本，可以在此指定。当前最新版本可在此链接获取。
`页脚` `boolean`	默认情况下，landing 页面显示一个包含指向配置文档链接的底部。要删除此底部，传递 `footer: false`。
`graphRef` `string`	如果提供，则 landing 页面包含一个（带自动选择重定向的）链接到相应 graph 的 Apollo Studio 页面graph ref。一个示例 graph ref 是 `my-graph@my-variant`。为了启用此链接，即使您已在别处提供用于使用报告和其他目的的 `graphRef`，您也需要在此处提供。这是因为如果您的服务器是公开可访问的，您可能不希望公开展示 graph ref。
`文档` `string`	一个 GraphQL document（例如，查询或突变），用于在 Studio Explorer 的编辑器中加载。如果您省略此信息，资源管理器初始加载将基于您的模式的一个示例查询。
`变量` `Record<string, any>`	一个包含初始变量值的对象，用于在加载Explorer时填充。如果提供，则这些变量应用于您在`document`中提供的初始查询。
`标题` `Record<string, string>`	包含初始HTTP标题值，以便在加载时填充到资源管理器中。
`embed` `布尔值 \| EmbeddableSandboxOptions`	如果为`true`或您提供了选项对象，Apollo Server的落地页面将渲染一个嵌入版的Apollo Sandbox，在它的GraphQL末端的URL中。这使得访客可以直接查询该端点，并使用其他Studio功能（如果用Apollo账户登录）。要嵌入Apollo Sandbox，必须也向Apollo Server提供要使用的Studio图层的graph ref，通常通过`APOLLO_GRAPH_REF`环境变量。默认值为`false`，在这种情况下，落地页面将显示基本的`curl`命令。您可以用显示和功能选项配置嵌入在您的Apollo Server端点的Explorer。有关受支持选项，请参阅`embed`选项。
`collectionId` & `operationId` `string`	用于在加载Explorer时填充的集合ID和操作ID。您可以通过点击在Studio中未经注册的图中操作旁边的...菜单并选择查看操作详情来找到这些值。
`includeCookies` `boolean`	一个布尔值，用来设置Studio Explorer是否应该在它的GraphQL请求中将cookies发送到您的服务器。如果您省略此设置，资源管理器会将`includeCookies`默认设置为`false`。

`embed` 选项

以下是可以包括在您传递给ApolloServerPluginLandingPageProductionDefault的embed选项中的

名称 / 类型	描述
`displayOptions` `Object`	包含与内嵌资源管理器页面加载时视觉状态相关的附加显示选项的对象。有关受支持子字段，请参阅`displayOptions`选项。
`persistExplorerState` `boolean`	如果为`true`，嵌入的Explorer使用`localStorage`来保存其状态（包括操作、标签、变量和报头），在用户会话之间保持状态。此状态将在页面加载时自动填充到Explorer中。如果为`false`，嵌入的Explorer将使用基于您 schema 的示例查询启动（除非您提供了`document`）。默认值为`false`。

`embed.displayOptions` 选项

以下是可以包括在您传递给嵌入Explorer插件的displayOptions选项中的

名称 / 类型	描述
`docsPanelState` `"open" \| "closed"`	如果`开启`，资源管理器文档面板（左侧栏）最初是展开的。如果`关闭`，面板最初是折叠的。默认值是`开启`。
`显示头部和环境变量` `真 \| 假`	如果`真`，嵌入的资源管理器包含请求头部和环境变量设置面板。如果`假`，则这些面板不存在。默认值是 `true`。
`主题` `“深色” \| “浅色”`	如果`深色`，资源管理器使用深色主题。如果`浅色`，使用浅色主题。默认值是`深色`。
`runTelemetry` `boolean`	如果设置为`false`，则Apollo服务器渲染的内嵌资源管理器不会初始化错误或事件跟踪。

默认情况下，Apollo Server 2 提供了 GraphQL Playground 登录页面。为了迁移目的，我们发布了@apollo/server-plugin-landing-page-graphql-playground包，这是一个与 Apollo Server 4 兼容的 GraphQL Playground 插件。然而，由于 GraphQL Playground 项目已经官方下线，我们不支持此插件的相关文档和安全更新。相反，我们建议您尽快迁移到活跃维护的Apollo Sandbox（Apollo Server 4 的默认登录页面）。

禁用登录页面

此ApolloServerPluginLandingPageDisabled插件从 Apollo Server 的基础 URL 不提供任何登录页面。安装它以在某些或不全部环境中禁用默认登录页面：

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginLandingPageDisabled()],
8
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginLandingPageDisabled()],
8
});

此插件不需要任何参数。

缓存控制

联合订阅

名称 / 类型	描述
`docsPanelState` `"open" \| "closed"`	如果`开启`，资源管理器文档面板（左侧栏）最初是展开的。如果`关闭`，面板最初是折叠的。默认值是`开启`。
`显示头部和环境变量` `真 \| 假`	如果`真`，嵌入的资源管理器包含请求头部和环境变量设置面板。如果`假`，则这些面板不存在。默认值是 `true`。
`主题` `“深色” \| “浅色”`	如果`深色`，资源管理器使用深色主题。如果`浅色`，使用浅色主题。默认值是`深色`。
`runTelemetry` `boolean`	如果设置为`false`，则Apollo服务器渲染的内嵌资源管理器不会初始化错误或事件跟踪。