Gatsby+Contentful GraphQL数组内片段解构报错问题求助

问题原因 #

Gatsby的Contentful源插件生成GraphQL Schema时，会根据实际存在的内容实例推断字段类型。当sections数组中只有ContentfulModelA或ContentfulModelB一种类型的实例时，插件会把sections的类型推断为该具体类型的数组（比如[ContentfulModelA]），而非预期的联合类型数组[ContentfulModelA | ContentfulModelB]。这就导致查询中另一个类型的片段无法被正确识别，触发类型不匹配的报错。

解决方案 #

方案1：手动强制指定Schema类型 #

通过Gatsby的createSchemaCustomization API，强制将ContentfulPage的sections字段定义为联合类型数组，绕过插件的自动推断逻辑。

1. 安装依赖：

npm install @graphql-tools/schema

2. 在gatsby-node.js中添加以下代码：

const { makeExecutableSchema } = require('@graphql-tools/schema');

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions;

  const typeDefs = `
    type ContentfulPage implements Node {
      sections: [ContentfulModelA | ContentfulModelB]
    }
  `;

  createTypes(typeDefs);
};

方案2：通过解析器强制维护类型标识 #

利用createResolvers API，在解析sections字段时确保每个元素都携带正确的__typename，让GraphQL始终识别为联合类型。

在gatsby-node.js中添加：

exports.createResolvers = ({ createResolvers }) => {
  createResolvers({
    ContentfulPage: {
      sections: {
        resolve: (source) => {
          return source.sections.map(item => ({
            ...item,
            // 确保__typename存在，避免类型推断偏差
            __typename: item.__typename || (item.fieldA ? 'ContentfulModelA' : 'ContentfulModelB')
          }));
        },
      },
    },
  });
};

方案3：Contentful内容模型层面优化 #

创建一个父内容类型（比如ContentfulSection），让ContentfulModelA和ContentfulModelB都继承这个父类型，然后将Page的sections字段设置为引用该父类型。

这样无论数组中存在哪种子类型，GraphQL都会将sections推断为父类型的数组，内联片段可以正常展开。修改后的查询示例：

export const query = graphql`
    query ComposablePageQuery($slug: String!) {
        contentfulPage(slug: { eq: $slug }) {
            __typename
            contentful_id
            slug
            sections {
                __typename
                contentful_id
                ... on ContentfulModelA {
                    fieldA
                    fieldB
                }
                ... on ContentfulModelB {
                    fieldC
                    fieldD
                }
            }
        }
    }
`;

方案对比 #

• 方案1：直接修改Schema，最直接高效，但需要手动维护类型定义，若Contentful模型变更需同步更新。
• 方案2：无需调整Contentful结构，通过代码修复类型推断问题，但依赖字段判断__typename，字段变更时需同步修改逻辑。
• 方案3：从内容模型层面规范设计，扩展性最好，是长期维护的最优解，但需要调整Contentful的现有模型结构。

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