从Apollo Server v2迁移至v3后，离线GraphQL Playground自定义配置加载失败问题

我刚完成从Apollo Server v2到v3的迁移，正好碰到和你一样的Playground配置问题，折腾了一下终于搞定了，给你分享具体的解决办法：

Apollo Server v3确实移除了构造函数里的playground属性，因为官方现在更推荐使用GraphiQL作为默认调试工具，但如果你还是想继续用GraphQL Playground（包括配置离线使用的自定义设置），需要手动集成它，步骤如下：

1. 安装GraphQL Playground依赖包 #

首先得安装官方提供的Playground HTML渲染包，执行以下命令：

# npm
npm install graphql-playground-html

# yarn
yarn add graphql-playground-html

2. 通过插件或自定义路由集成Playground #

v3使用插件系统扩展功能，你可以通过两种方式添加Playground：

方式一：替换默认的Landing Page #

如果你想把Playground作为服务器启动后的默认页面（比如访问根路径就打开Playground），可以在Apollo Server的plugins配置里实现：

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { renderPlaygroundPage } from 'graphql-playground-html';

// 你的typeDefs和resolvers
const typeDefs = `#graphql
  type Query {
    hello: String
  }
`;
const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    {
      async serverWillStart() {
        return {
          async renderLandingPage() {
            // 渲染Playground页面并传入自定义配置
            return {
              html: renderPlaygroundPage({
                endpoint: '/graphql', // 你的GraphQL接口地址
                // 这里填写你的离线相关自定义配置，和v2里的playground.settings对应
                settings: {
                  'offline.enabled': true, // 启用离线模式
                  'persistedQueries.enabled': true, // 启用持久化查询支持离线
                  'editor.theme': 'dark', // 其他自定义设置示例
                  'request.credentials': 'include',
                },
              }),
            };
          },
        };
      },
    },
  ],
});

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`Server ready at ${url}`);

方式二：添加独立的Playground路由 #

如果你想保留默认的Apollo Landing Page，只在特定路由（比如/playground）打开Playground，可以结合Express等框架添加自定义路由（以Express为例）：

import express from 'express';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { renderPlaygroundPage } from 'graphql-playground-html';
import { json } from 'body-parser';

const app = express();
const PORT = 4000;

// 你的typeDefs和resolvers
const typeDefs = `#graphql
  type Query {
    hello: String
  }
`;
const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
await server.start();

// 添加Playground专属路由
app.get('/playground', (req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.send(
    renderPlaygroundPage({
      endpoint: '/graphql',
      settings: {
        'offline.enabled': true, // 离线模式配置
        // 其他你需要的自定义设置
      },
    })
  );
});

// 挂载GraphQL接口
app.use('/graphql', json(), expressMiddleware(server));

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
  console.log(`Playground available at http://localhost:${PORT}/playground`);
});

关键说明 #

• v3把Playground从核心包中移除，所以必须手动安装依赖
• 原来v2里playground属性中的配置项，现在可以通过renderPlaygroundPage的settings参数传入，格式完全一致
• 离线相关的配置（比如启用离线模式、持久化查询）都可以在settings里设置，和v2的用法一样

内容的提问来源于stack exchange，提问作者TalS