Gatsby-Source-Wordpress编译报错：TypeError无法解构nodesType的fields

AI 小北

2026-8-10

排查Gatsby与WordPress集成的TypeError错误

运行gatsby develop时出现编译错误：TypeError: Cannot destructure property 'fields' of 'nodesType' as it is undefined，错误栈指向gatsby-source-wordpress相关模块。本人未修改代码或升级依赖，此前一直在其他项目工作，已尝试禁用部分WordPress插件、升级gatsby-source-wordpress插件、删除node_modules及package-lock.json后用npm i --legacy-peer-deps重装依赖，但问题仍存在。以下是相关配置与代码，请问该从何处开始排查？

错误详情

TypeError: Cannot destructure property 'fields' of 'nodesType' as it is undefined.
    at generateNodeQueriesFromIngestibleFields (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/steps/ingest-remote-schema/build-queries-from-introspection/generate-queries-from-ingestable-types.js:155:13)
    at buildNodeQueries (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/steps/ingest-remote-schema/build-queries-from-introspection/build-node-queries.js:25:25)
    at runSteps (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/utils/run-steps.ts:41:9)
    at runSteps (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/utils/run-steps.ts:43:9)
    at ingestRemoteSchema (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/steps/ingest-remote-schema/index.js:49:5)
    at runSteps (/Users/repoFolder/Work/gatsby/node_modules/gatsby-source-wordpress/src/utils/run-steps.ts:41:9)
    at runAPI (/Users/repoFolder/Work/gatsby/node_modules/gatsby/src/utils/api-runner-node.js:487:16)


 ERROR #gatsby-source-wordpress_112003 

 gatsby-source-wordpress 

        Encountered a critical error when running the buildNodeQueries build step.
        See above for more information.

not finished createSchemaCustomization - 3.831s
not finished [gatsby-source-wordpress] ingest WPGraphQL schema - 2.379s

gatsby-config.js配置

{
    resolve: "gatsby-source-wordpress",
    options: {
        url: `${process.env.WPGRAPHQL_URL}`,
        verbose: false,
        develop: {
            hardCacheData: false,
        },
        schema: {
            perPage: 10, // currently set to 100
            requestConcurrency: 3, // currently set to 15
            previewRequestConcurrency: 1, // currently set to 5
        },
        type: {
            Page: {
                exclude: true,
            },
            Menu: {
                exclude: true,
            },
            MenuItem: {
                exclude: true,
            },
        },
        debug: {
            graphql: {
                onlyReportCriticalErrors: true,
            },
        },
        searchAndReplace: [
            {
                search: `${process.env.GATSBY_WORDPRESS_URL_PROTOCOL}://${process.env.GATSBY_WORDPRESS_URL_PATH}`,
                replace: `${process.env.GATSBY_SITE_URL_PROTOCOL}://${process.env.GATSBY_SITE_URL_PATH}`,
            },
        ],
        html: {
            useGatsbyImage: true,
        },
    },
},

gatsby-node.js代码

exports.createPages = async ({ graphql, actions, reporter }) => {
    const { createPage } = actions

    const BlogPostTemplate = path.resolve("./src/templates/BlogPost.tsx")
    const BlogTagPostsTemplate = path.resolve(
        "./src/templates/BlogTagPosts.tsx"
    )
    const BlogCategoryPostsTemplate = path.resolve(
        "./src/templates/BlogCategoryPosts.tsx"
    )

    const BlogPostsResult = await graphql(`
        {
            allWpPost {
                edges {
                    node {
                        id
                        slug
                        uri
                        link
                        title
                        excerpt
                        date(formatString: "MMMM DD, YYYY")
                        modified(formatString: "MMMM DD, YYYY")
                        author {
                            node {
                                avatar {
                                    url
                                }
                                id
                                name
                                uri
                                slug
                            }
                        }
                        featuredImage {
                            node {
                                localFile {
                                    childImageSharp {
                                        gatsbyImageData(
                                            width: 1920
                                            placeholder: BLURRED
                                            formats: [AUTO, WEBP, AVIF]
                                        )
                                    }
                                }
                            }
                        }
                        categories {
                            nodes {
                                id
                                count
                                name
                                slug
                            }
                        }
                        tags {
                            nodes {
                                id
                                count
                                name
                                slug
                            }
                        }
                    }
                }
            }
        }
    `)

    if (BlogPostsResult.errors) {
        reporter.panicOnBuild("Error while running GraphQL query.")
        return
    }

    const BlogPosts = BlogPostsResult.data.allWpPost.edges

    BlogPosts.forEach((post, index) => {
        const date = post.node.date
        createPage({
            path: `/${post.node.categories.nodes[0].slug}/${moment(date).format(
                "YYYY"
            )}/${moment(date).format("MM")}/${post.node.slug}.html`,
            component: BlogPostTemplate,
            context: {
                id: post.node.id,
                slug: post.node.slug,
                uri: post.node.uri,
                previous: index === 0 ? null : BlogPosts[index - 1].node,
                next:
                    index === BlogPosts.length - 1
                        ? null
                        : BlogPosts[index + 1].node,
            },
        })
    })

    createPaginatedPages({
        edges: BlogPosts,
        createPage: createPage,
        pageTemplate: "src/templates/BlogPosts.tsx",
        pageLength: 10,
        pathPrefix: "blog",
    })

    const BlogTagPosts = new Map()
    const BlogCategoryPosts = new Map()

    BlogPosts.forEach((post) => {
        const tags = post.node.tags.nodes
        if (tags && tags.length > 0) {
            tags.forEach((tag) => {
                if (BlogTagPosts.has(tag.slug)) {
                    BlogTagPosts.set(tag.slug, [
                        ...BlogTagPosts.get(tag.slug),
                        post,
                    ])
                } else {
                    BlogTagPosts.set(tag.slug, [post])
                }
                if (BlogTagPosts.has(tag.title)) {
                    BlogTagPosts.set(tag.title, [
                        ...BlogTagPosts.get(tag.title),
                        post,
                    ])
                } else {
                    BlogTagPosts.set(tag.title, [post])
                }
            })
        }
        const categories = post.node.categories.nodes
        if (categories && categories.length > 0) {
            categories.forEach((category) => {
                if (BlogCategoryPosts.has(category.slug)) {
                    BlogCategoryPosts.set(category.slug, [
                        ...BlogCategoryPosts.get(category.slug),
                        post,
                    ])
                } else {
                    BlogCategoryPosts.set(category.slug, [post])
                }
                if (BlogCategoryPosts.has(category.title)) {
                    BlogCategoryPosts.set(category.title, [
                        ...BlogCategoryPosts.get(category.title),
                        post,
                    ])
                } else {
                    BlogCategoryPosts.set(category.title, [post])
                }
            })
        }
    })

    const BlogTagSlugs = [...BlogTagPosts.keys()]
    const BlogCategorySlugs = [...BlogCategoryPosts.keys()]
    //const BlogCategoryTitles = [...BlogCategoryPosts.keys()];

    if (BlogTagSlugs.length > 0) {
        BlogTagSlugs.forEach((BlogTagSlug) => {
            createPage({
                path: `/tag/${BlogTagSlug}`,
                component: BlogTagPostsTemplate,
                context: {
                    group: BlogTagPosts.get(BlogTagSlug),
                    slug: BlogTagSlug,
                    title: BlogTagPosts.get("tag.title"),
                },
            })
        })
    }

    if (BlogCategorySlugs.length > 0) {
        BlogCategorySlugs.forEach((BlogCategorySlug) => {
            createPage({
                path: `/category/${BlogCategorySlug}`,
                component: BlogCategoryPostsTemplate,
                context: {
                    group: BlogCategoryPosts.get(BlogCategorySlug),
                    slug: BlogCategorySlug,
                    title: BlogCategoryPosts.get("category.title"),
                },
            })
        })
    }
}

排查步骤

1. 验证WPGraphQL服务与Schema完整性

直接访问你的WPGRAPHQL_URL，执行以下查询确认服务正常，同时检查所有类型是否包含fields：
```
query {
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}
```
如果发现某个类型没有fields，大概率是WordPress端的自定义类型或插件导致Schema异常。

2. 排查WordPress端问题

全量禁用第三方插件：只保留WPGraphQL核心插件，重启WordPress后再运行gatsby develop，若恢复正常则逐个启用插件定位问题源。
检查WPGraphQL版本：确保WordPress端的WPGraphQL版本与gatsby-source-wordpress版本兼容（比如gatsby-source-wordpress v7需要WPGraphQL v1及以上）。
重置WPGraphQL Schema：在WordPress后台的WPGraphQL设置中执行Schema重置，清除可能的缓存或异常定义。

3. 调整Gatsby配置与缓存

移除类型排除规则：暂时注释gatsby-config.js中type字段下的排除配置，测试是否是规则导致Schema解析失败。
开启详细调试：将verbose设为true，debug.graphql.onlyReportCriticalErrors设为false，重新运行获取更详细的错误日志。
清除Gatsby缓存：执行gatsby clean后再启动开发服务，避免旧缓存干扰。

4. 检查依赖兼容性

确认package.json中gatsby与gatsby-source-wordpress版本匹配，比如gatsby-source-wordpress v7需要Gatsby v4+。
尝试降级gatsby-source-wordpress到之前稳定运行的版本，排除新版本的兼容性问题。

5. 验证环境变量

确认WPGRAPHQL_URL环境变量正确，协议（http/https）、域名、路径均无拼写错误。

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

Gatsby-Source-Wordpress编译报错：TypeError无法解构nodesType的fields

错误详情 #

gatsby-config.js配置 #

gatsby-node.js代码 #

排查步骤 #

1. 验证WPGraphQL服务与Schema完整性 #

2. 排查WordPress端问题 #

3. 调整Gatsby配置与缓存 #

4. 检查依赖兼容性 #

5. 验证环境变量 #