如何通过GraphQL API将Payload CMS数据传输至Next.js前端？

一、核心问题拆解 #

• 跨域错误（http://localhost:5000/graphql）：Payload的GraphQL端点默认是/api/graphql，根路径/graphql不存在；且前后端端口不同（Next.js通常为3000，Payload为5000），浏览器同源策略拦截跨域请求。
• GraphQL查询错误（http://localhost:5000/api/graphql）：查询语句不符合Payload的GraphQL规范，或集合权限配置未开放读取权限。

二、Payload CMS 必要配置调整 #

1. 启用CORS与GraphQL基础配置 #

在payload.config.ts中添加跨域允许规则，确保前端域名可访问：

import { buildConfig } from 'payload/config';
import path from 'path';

export default buildConfig({
  // 其他已有配置...
  graphQL: {
    schemaOutputFile: path.resolve(__dirname, 'generated-schema.graphql'),
  },
  // 允许前端域名跨域请求，替换为你的Next.js实际端口
  cors: ['http://localhost:3000'],
});

2. 开放集合读取权限 #

如果你的books集合需要未授权访问（仅开发环境建议），在集合配置文件（如collections/Books.ts）中设置：

import { CollectionConfig } from 'payload/types';

export const Books: CollectionConfig = {
  slug: 'books',
  access: {
    // 开发环境允许所有人读取，生产环境需根据业务需求配置权限逻辑
    read: () => true,
  },
  fields: [
    // 你的字段定义：title、author、description等
  ],
};

三、前端代码修正 #

1. 修正Apollo客户端端点 #

Payload的GraphQL正确端点为/api/graphql，更新客户端配置：

import { ApolloClient, InMemoryCache } from "@apollo/client";

const client = new ApolloClient({
  uri: "http://localhost:5000/api/graphql",
  cache: new InMemoryCache(),
});

export default client;

2. 修正GraphQL查询语句 #

Payload的集合查询名称默认使用小驼峰格式（如books而非Books），调整查询语句：

const GET_BOOKS = gql`
  query GetBooks {
    books {
      docs {
        id
        title
        author {
          name
        }
        description
      }
    }
  }
`;

3. 简化组件内的Query调用 #

由于已通过ApolloProvider全局注入客户端，无需在useQuery中重复传入client参数：

"use client";

import { gql, useQuery } from "@apollo/client";

const GET_BOOKS = gql`
  query GetBooks {
    books {
      docs {
        id
        title
        author {
          name
        }
        description
      }
    }
  }
`;

type Book = {
  id: string;
  title: string;
  author: {
    name: string;
  };
  description: string;
};

const Books = () => {
  const { loading, error, data } = useQuery(GET_BOOKS);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  const books: Book[] = data.books.docs;

  return (
    <div>
      <h1 className="font-bold text-center mt-10 text-3xl">Book Page</h1>
      <div className="mt-8">
        {books.map(book => (
          <div key={book.id} className="p-4 border mb-4">
            <h2 className="text-xl font-semibold">{book.title}</h2>
            <p className="text-gray-600">作者：{book.author.name}</p>
            <p className="mt-2">{book.description}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

export default Books;

四、验证步骤 #

1. 重启Payload CMS与Next.js服务，确保配置生效。
2. 访问http://localhost:5000/api/graphql打开GraphQL Playground，测试查询语句是否能正常返回数据：

query {
  books {
    docs {
      id
      title
      author {
        name
      }
      description
    }
  }
}

3. 前端页面访问后，若控制台无报错且能渲染图书列表，则配置成功。

内容的提问来源于stack exchange，提问作者A.H JIM