Apollo持久化查询过长触发HTTP 414，如何仅用queryId请求？

1. 先确认GraphQL Codegen的配置没毛病 #

要保证codegen真的生成了带哈希ID的持久化查询文件，而且前后端都能访问。打开你的codegen.ts，检查是不是加了persisted-query插件，参考配置如下：

// codegen.ts 示例配置
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'https://你的WordPress站点域名/graphql',
  documents: ['./src/**/*.graphql'],
  generates: {
    // 把持久化查询JSON生成到公共目录，确保后端能读取
    './public/persisted-queries.json': {
      plugins: ['persisted-query'],
      config: {
        hashAlgorithm: 'sha256', // 和WordPress插件支持的哈希算法对齐，一般用SHA256
        outputAsJson: true, // 输出格式为 { 查询ID: 查询字符串 }
      },
    },
    // 可选：生成TypeScript类型，方便开发
    './src/generated/graphql.ts': {
      plugins: ['typescript', 'typescript-operations', 'typescript-react-apollo'],
    },
  },
};

export default config;

运行graphql-codegen后，去public/persisted-queries.json看看，是不是有哈希ID作为键、对应查询字符串作为值的键值对。

2. 给Apollo Client加持久化查询Link #

在Next.js的Apollo Client初始化文件（比如src/lib/apollo-client.ts）里，要把createPersistedQueryLink和createHttpLink组合起来，让客户端优先发查询ID而非完整查询：

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { sha256 } from 'crypto-hash'; // 先装这个包：npm install crypto-hash

// 创建持久化查询Link，指定哈希算法
const persistedQueryLink = createPersistedQueryLink({
  sha256, // 和codegen用的哈希算法必须一致
  useGETForHashedQueries: true, // 如果后端支持GET请求，开这个可以让哈希查询用GET；敏感查询别开
});

// 指向WordPress的GraphQL端点
const httpLink = createHttpLink({
  uri: 'https://你的WordPress站点域名/graphql',
});

// 注意Link顺序：持久化查询Link要放在HTTP Link前面
const client = new ApolloClient({
  link: persistedQueryLink.concat(httpLink),
  cache: new InMemoryCache(),
});

export default client;

如果你的WordPress后端不接受GET方式的持久化查询，把useGETForHashedQueries设为false，默认用POST发送查询ID。

3. 确保WordPress后端支持持久化查询 #

WordPress这边得配好对应的插件：

• 用WPGraphQL的话，安装并激活WPGraphQL Persisted Queries插件（官方或社区版都行）
• 配置插件允许从你的persisted-queries.json文件加载查询，或者开启动态哈希验证（如果是动态生成查询的场景）
• 确认服务器配置没拦截/persisted-queries.json的访问，比如Nginx/Apache的规则要允许这个文件被读取

4. 验证请求是否正常发送查询ID #

启动Next.js项目后，开浏览器开发者工具的Network标签，看GraphQL请求：

• GET请求的话，URL里应该带extensions={"persistedQuery":{"version":1,"sha256Hash":"你的查询ID"}}或者queryId=你的查询ID
• POST请求的话，请求体里要有persistedQuery字段，而不是完整的query字符串

如果还是发完整查询，排查这几点：

• 手动算一下查询字符串的SHA256哈希，对比persisted-queries.json里的ID，确保一致
• 检查Apollo Client的Link顺序，持久化查询Link必须在最前面，不能被其他Link覆盖
• 有没有其他自定义Link（比如错误处理、权限验证Link）干扰了持久化查询的逻辑

5. 临时应急：避免HTTP 414错误 #

如果暂时搞不定持久化查询，先把请求改成POST，把查询放在请求体里，就不会触发URL过长的414了。修改HTTP Link配置：

const httpLink = createHttpLink({
  uri: 'https://你的WordPress站点域名/graphql',
  headers: {
    'Content-Type': 'application/json',
  },
});

这只是临时方案，最终还是要让持久化查询生效来优化请求。

内容的提问来源于stack exchange，提问作者constantijn van hartesveldt