Gatsby V3升级V4后GraphQL片段报错：kontentCta不存在

问题背景 #

将项目从Gatsby V3升级至V4，依赖安装完成后构建失败，报错：GraphQL查询出错：片段‘kontentCta’不存在。该片段为项目全局复用片段，V3版本下可正常运行，升级后失效，已查阅Gatsby官方迁移文档未找到对应解决方案。

全局片段kontentCta代码 #

export const fragmentCta = graphql`
  fragment kontentCta on kontent_item_content_item___cta {
        elements {
            cta_label {
                value
            }
            cta_location {
                ...kontentCtaLocation
            }
            cta_location_anchor_point {
                value
            }
            cta_window_action {
                value {
                    codename
                }
            }
        }
    }
`;

使用片段的组件查询代码 #

export const fragmentCtaBar = graphql`
    fragment CtaBar on kontent_item_component___cta_bar {
        elements {
            ctas {
                value {
                    ...kontentCta
                }
            }
            layout {
                value {
                    name
                }
            }
            content_panel__content_panel_font_color {
                value {
                    ... on kontent_item_list___brand_colors {
                        id
                        elements {
                            color_hex_value {
                                value
                            }
                        }
                    }
                }
            }
            type_of_cta {
                value {
                    codename
                }
            }
            form_link {
                value
            }
            form_cta_label {
                value
            }
        }
    }
`;

项目package.json配置 #

{
    "dependencies": {
            "@babylonjs/core": "^4.2.1",
            "@babylonjs/gui": "^4.2.1",
            "@babylonjs/loaders": "^4.2.1",
            "@kontent-ai/gatsby-components": "9.1.0",
            "@kontent-ai/gatsby-source": "9.1.0",
            "@types/react-modal": "^3.12.0",
            "algoliasearch": "^4.12.1",
            "axios": "^0.25.0",
            "css-minimizer-webpack-plugin": "^3.4.1",
            "date-fns": "^2.28.0",
            "framer-motion": "^6.2.6",
            "gatsby-image": "^3.11.0",
            "gatsby-plugin-algolia": "^0.26.0",
            "gatsby-plugin-breakpoints": "^1.3.6",
            "gatsby-plugin-google-tagmanager": "^4.24.0",
            "gatsby-plugin-image": "^2.24.0",
            "gatsby-plugin-react-helmet": "^5.24.0",
            "gatsby-plugin-readingtime": "^2.1.0",
            "gatsby-plugin-robots-txt": "^1.7.0",
            "gatsby-plugin-sharp": "^4.24.0",
            "gatsby-plugin-sitemap": "^5.24.0",
            "gatsby-plugin-zeit-now": "^0.5.0",
            "gatsby-transformer-remark": "^5.24.0",
            "gatsby-transformer-sharp": "^4.24.0",
            "html-react-parser": "^0.14.3",
            "js-cookie": "^3.0.1",
            "lodash": "^4.17.15",
            "lodash.get": "^4.4.2",
            "mini-css-extract-plugin": "^2.5.3",
            "postcss-loader": "^6.2.1",
            "postcss-url": "^10.1.3",
            "proxy-polyfill": "^0.3.2",
            "react": "^17.0.0",
            "react-autosuggest": "^10.1.0",
            "react-babylonjs": "^3.0.17",
            "react-dom": "^17.0.0",
            "react-dropdown": "^1.9.2",
            "react-helmet": "^6.1.0",
            "react-hook-form": "^6.15.8",
            "react-instantsearch-dom": "^6.22.0",
            "react-jotform-embed": "^1.1.1",
            "react-modal": "^3.14.3",
            "react-player": "^2.9.0",
            "react-select": "^5.2.2",
            "react-toastify": "^8.2.0",
            "react-truncate": "^2.4.0",
            "sharp": "^0.30.1",
            "typescript-plugin-css-modules": "^3.4.0",
            "webpack": "^5.69.0"
        },
        "devDependencies": {
            "@babel/core": "^7.17.4",
            "@storybook/addon-actions": "^6.4.19",
            "@storybook/addon-essentials": "^6.4.19",
            "@storybook/addon-links": "^6.4.19",
            "@storybook/react": "^6.4.19",
            "@svgr/webpack": "^6.2.1",
            "@testing-library/jest-dom": "^5.16.1",
            "@testing-library/react": "^11.2.7",
            "@types/jest": "^26.0.1",
            "@types/node": "^17.0.18",
            "@types/react": "^17.0.39",
            "@types/react-autosuggest": "^10.0.1",
            "@types/react-dom": "^17.0.8",
            "@types/react-helmet": "^6.1.5",
            "@types/react-instantsearch-dom": "^6.12.2",
            "@types/react-truncate": "^2.3.3",
            "@types/typeform__embed": "^1.0.0",
            "babel-eslint": "^10.1.0",
            "babel-jest": "26.0.1",
            "babel-loader": "^8.2.2",
            "babel-preset-gatsby": "^2.7.0",
            "chalk": "^5.0.0",
            "core-js": "^3.21.0",
            "cross-env": "^7.0.3",
            "css-loader": "^6.6.0",
            "cypress": "^9.5.0",
            "dotenv": "^16.0.0",
            "eslint": "^7.32.0",
            "eslint-plugin-react": "^7.28.0",
            "gatsby": "^4.0.0",
            "gatsby-plugin-postcss": "^5.24.0",
            "gatsby-plugin-webpack-bundle-analyser-v2": "^1.1.27",
            "gh-pages": "^2.2.0",
            "husky": "^4.3.6",
            "identity-obj-proxy": "^3.0.0",
            "inquirer": "^7.1.0",
            "jest": "^26.6.3",
            "jest-junit": "^12.2.0",
            "lint-staged": "^10.5.3",
            "npm-force-resolutions": "0.0.3",
            "postcss": "^8.4.6",
            "postcss-custom-properties": "^12.1.4",
            "postcss-easy-import": "^3.0.0",
            "postcss-import": "^14.0.2",
            "postcss-mixins": "^9.0.1",
            "postcss-nested": "^5.0.6",
            "postcss-preset-env": "^7.4.0",
            "prettier": "^2.3.1",
            "react-test-renderer": "^17.0.1",
            "rimraf": "^3.0.2",
            "storybook-css-modules-preset": "^1.1.1",
            "ts-jest": "26.0.0",
            "yargs-parser": "^21.0.0"
        },
        "peerDependencies": {
            "gatsby": "^4.0.0"
        },
        "overrides": {
            "gatsby-plugin-robots-txt": {
                "gatsby": "4.25.4"
            }
        },
        "engines": {
            "node": "<=16.18.1"
        },
        "keywords": [
            "gatsby"
        ]
}

解决方案 #

1. 确保片段被正确加载 #

Gatsby V4对GraphQL片段的扫描逻辑有调整，可采取以下措施：

• 将全局片段文件统一放在src/fragments目录下，Gatsby会自动识别该目录并优先加载其中的片段
• 若未使用上述目录，在所有引用kontentCta的组件文件顶部导入片段定义文件，例如：

  import '../path-to-fragment-file/fragmentCta'
  

2. 修复片段定义的语法错误 #

原fragmentCta代码中存在多余的反引号，导致Gatsby无法正确解析片段。修正后的代码需移除片段开头的多余反引号（已在上方代码块中修正）。

3. 更新Kontent相关插件版本 #

当前使用的@kontent-ai/gatsby-source和@kontent-ai/gatsby-components版本9.1.0可能与Gatsby V4存在兼容性问题，尝试升级到最新兼容版本：

npm update @kontent-ai/gatsby-source @kontent-ai/gatsby-components

4. 清除缓存后重新构建 #

Gatsby V4的缓存可能残留V3的旧查询数据，执行以下命令清除缓存并重新构建：

gatsby clean && gatsby build

5. 检查嵌套片段的可用性 #

kontentCta中引用了kontentCtaLocation片段，需确保该片段同样被正确定义和加载，否则会间接导致kontentCta无法被识别。

内容的提问来源于stack exchange，提问作者Md Afzaal Khan