Next.js项目：GraphQL查询Contentful的imagesCollection仅返回单张图片

问题描述 #

我在开发Next.js + Contentful CMS项目时，遇到一个异常：通过GraphQL查询房间详情时，imagesCollection.items仅返回1张图片，但Contentful后台中该房间明明关联了多张图片。roomType、hotelSlug等其他字段均可正常获取。

使用的查询语句：

{
  roomsCollection(where: { id: "ROOM_ID" }, order: id_ASC) {
    items {
      id
      roomType
      hotelSlug
      included
      imagesCollection {
        items {
          title
          description
          url
          fileName
        }
      }
    }
  }
}

对应的Next.js数据获取函数：

export async function getRoomDetailsById(
  id: string
): Promise<{ RoomCollectionItem: RoomCollectionType[] }> {
  const response = await fetch(ApiUrl, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        {
          roomsCollection(where: { id: "${id}" }, order: id_ASC) {
            items {
              id
              roomType
              hotelSlug
              included
              imagesCollection {
                items {
                  title
                  description
                  url
                  fileName
                }
              }
            }
          }
        }
      `,
    }),
  });

  const json: ApiResponse = await response.json();
  console.log(json.data.roomsCollection.items[0].imagesCollection.items);
  
  return {
    RoomCollectionItem: json.data.roomsCollection.items,
  };
}

已完成的排查：

• 确认Contentful中所有图片均已上传并发布
• 在Contentful GraphQL Playground执行相同查询，可正常返回所有图片
• 其他字段数据获取正常

可能的解决方案 #

1. 显式设置图片集合的查询上限 #

Contentful GraphQL API对集合类型有默认分页限制，即使Playground中默认返回更多结果，代码中可能需要显式指定limit参数确保返回所有关联图片：

imagesCollection(limit: 100) { # 根据实际需要调整limit值
  items {
    title
    description
    url
    fileName
  }
}

2. 改用GraphQL变量传递ID #

避免字符串拼接id可能导致的潜在语法问题，改用变量方式传递参数，同时提升代码可维护性：

export async function getRoomDetailsById(
  id: string
): Promise<{ RoomCollectionItem: RoomCollectionType[] }> {
  const response = await fetch(ApiUrl, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query GetRoomDetails($id: String!) {
          roomsCollection(where: { id: $id }, order: id_ASC) {
            items {
              id
              roomType
              hotelSlug
              included
              imagesCollection(limit: 100) {
                items {
                  title
                  description
                  url
                  fileName
                }
              }
            }
          }
        }
      `,
      variables: { id },
    }),
  });

  const json: ApiResponse = await response.json();
  console.log(json.data.roomsCollection.items[0].imagesCollection.items);
  
  return {
    RoomCollectionItem: json.data.roomsCollection.items,
  };
}

3. 校验API环境与令牌一致性 #

确认代码中使用的ApiUrl和NEXT_PUBLIC_CONTENTFUL_ACCESS_KEY与Playground中完全匹配：

• 生产环境URL：https://graphql.contentful.com/content/v1/spaces/{SPACE_ID}，对应生产访问令牌
• 预览环境URL：https://preview.contentful.com/content/v1/spaces/{SPACE_ID}，对应预览访问令牌
  如果环境不匹配，可能导致获取的数据不一致。

4. 二次确认生产环境的条目状态 #

虽然已确认图片已发布，但需再次检查Contentful生产环境中，该房间条目是否确实关联并发布了所有图片（避免仅在预览环境完成操作，未同步到生产）。

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