Next.js+TypeScript项目Strapi GraphQL数据map遍历报错排查

问题根源 #

你遇到的错误本质是尝试对单个Font对象调用数组的map方法，而非对Font数组调用。这通常是因为没有正确获取Strapi返回的列表数据，或是GraphQL查询/自动生成的类型存在路径错误。

分步解决 #

1. 确认GraphQL查询的正确性

先检查你的GraphQL查询是否请求的是字体列表（复数形式），而非单个字体。Strapi的GraphQL API中，集合类型的查询默认用复数命名，比如fonts对应字体集合，单数font一般是根据ID获取单个资源。正确的查询示例：

query GetFontList {
  fonts {
    id
    name
  }
}

2. 核对codegen生成的类型

查看codegen生成的查询类型（比如GetFontListQuery），确认结构符合数组预期：

type GetFontListQuery = {
  __typename?: 'Query';
  fonts: Array<{
    __typename?: 'Font';
    id: string;
    name: string;
  }>;
};

如果生成的类型里fonts是单个Font而非数组，说明你的GraphQL查询用了单数font，需要修改为复数后重新运行codegen更新类型。

3. 正确获取并遍历数据

在React组件中，确保从useQuery返回的data里正确取出数组，同时处理异步状态：

import { useQuery } from '@apollo/client';
import { GetFontListDocument, GetFontListQuery } from '../generated/graphql';

export default function FontListPage() {
  const { data, loading, error } = useQuery<GetFontListQuery>(GetFontListDocument);

  if (loading) return <div>加载中...</div>;
  if (error) return <div>加载失败：{error.message}</div>;

  // 用空数组兜底，避免undefined报错
  const fontList = data?.fonts || [];

  return (
    <div className="font-list">
      {fontList.map((font) => (
        <div key={font.id} className="font-item">
          {font.name}
        </div>
      ))}
    </div>
  );
}

重点：

• 必须通过data.fonts获取数组，不能直接对data调用map
• 用|| []兜底，防止data或data.fonts为undefined时触发报错

4. 匹配控制台返回的JSON结构

根据你提供的接口返回JSON，确认数组所在的准确路径。比如如果返回结构是：

{
  "data": {
    "fonts": [
      {"id": "1", "name": "思源黑体"},
      {"id": "2", "name": "Roboto"}
    ]
  }
}

就必须通过data.fonts获取数组，而非其他错误路径（比如data.font）。

常见误区 #

• 混淆Strapi GraphQL的单数/复数查询：单数font返回单个资源，复数fonts返回列表
• 忽略useQuery的异步状态：直接访问data.fonts可能得到undefined，必须处理加载、错误状态
• codegen类型与查询不匹配：修改查询后要重新运行codegen更新类型

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