Gatsby v4在AWS Amplify随机构建失败：String类型字段[x]无亚字段

问题描述 #

使用Gatsby v4搭建网站，本地构建始终正常，但在AWS Amplify构建时会随机出现若干GraphQL查询错误，错误格式为：

Field "[x]" must not have a selection since type "String" has no subfields.

这类错误通常因文件路径（多为图片路径）拼写或格式错误，导致GraphQL将其识别为String类型而非文件路径。错误数量随机，每次1-3个左右，约35%的构建可正常完成无错误。

当前package.json配置如下：

{
  "scripts": {
    "develop": "cross-env GATSBY_GRAPHQL_IDE=playground gatsby develop -H 0.0.0.0",
    "start": "gatsby develop",
    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,css}\"",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "clean": "gatsby clean"
  },
  "dependencies": {
    "@aws-amplify/api": "^4.0.53",
    "@pittica/gatsby-plugin-recaptcha": "^2.0.3",
    "aws-amplify": "^4.3.35",
    "gatsby": "^4.24.4",
    "gatsby-cli": "^4.24.0",
    "gatsby-plugin-anchor-links": "^1.2.1",
    "gatsby-plugin-html-attributes": "^1.0.5",
    "gatsby-plugin-image": "^2.16.1",
    "gatsby-plugin-manifest": "^4.13.0",
    "gatsby-plugin-robots-txt": "1.7.1",
    "gatsby-plugin-sharp": "^4.16.1",
    "gatsby-plugin-sitemap": "^5.24.0",
    "gatsby-source-build-date": "^1.0.1",
    "gatsby-source-filesystem": "^4.16.0",
    "gatsby-transformer-csv": "^4.23.0",
    "gatsby-transformer-json": "^4.16.0",
    "gatsby-transformer-remark": "^5.22.0",
    "gatsby-transformer-sharp": "^4.16.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-icons": "^4.3.1"
  },
  "devDependencies": {
    "cross-env": "^7.0.3",
    "prettier": "^2.6.2"
  }
}

已尝试更新依赖、切换Node/npm版本、修改构建命令，均无法解决问题。

解决方案 #

1. 强制构建前清理缓存 #

AWS Amplify默认复用构建缓存，可能残留旧的GraphQL类型定义干扰构建。修改package.json的build命令，强制在构建前清理缓存：

"build": "gatsby clean && gatsby build"

同时在AWS Amplify构建设置中，确保不跳过缓存清理（若之前配置过跳过）。

2. 明确指定文件路径的GraphQL类型 #

对于JSON/CSV等数据源中的文件路径字段，在gatsby-node.js中用createTypes强制定义为File类型，避免Gatsby自动推断出错：

exports.createTypes = ({ actions }) => {
  const { createTypes } = actions;
  const typeDefs = `
    type YourJsonNode implements Node {
      imagePath: File @fileByRelativePath
    }
    type YourCsvNode implements Node {
      imgUrl: File @fileByRelativePath
    }
  `;
  createTypes(typeDefs);
};

替换YourJsonNode、YourCsvNode为实际节点类型，imagePath、imgUrl为对应路径字段名。

3. 确保异步数据源加载完成 #

若使用异步数据源（如API获取数据），在sourceNodes中等待所有数据加载完成后再创建节点，避免类型推断时机错误：

exports.sourceNodes = async ({ actions, createNodeId, createContentDigest }) => {
  const { createNode } = actions;
  // 等待异步数据获取完成
  const data = await fetchYourData();
  // 遍历创建节点
  data.forEach(item => {
    const node = {
      ...item,
      id: createNodeId(`your-node-${item.id}`),
      parent: null,
      children: [],
      internal: {
        type: 'YourAsyncNode',
        contentDigest: createContentDigest(item),
      },
    };
    createNode(node);
  });
};

4. 锁定依赖版本 #

当前部分依赖使用^前缀，可能导致Amplify构建时安装不同版本依赖引发兼容性问题。将所有Gatsby相关依赖版本锁定为固定值（去掉^），例如：

"gatsby": "4.24.4",
"gatsby-plugin-image": "2.16.1",
"gatsby-plugin-sharp": "4.16.1"
// 其他Gatsby依赖同理

5. 添加Amplify构建环境变量 #

在AWS Amplify构建设置中添加环境变量GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true，让Gatsby在数据变化时重新构建页面，减少缓存导致的类型推断错误。

验证步骤 #

1. 应用上述任意修改后，提交代码触发Amplify构建
2. 连续触发5-10次构建，确认是否不再出现随机GraphQL错误

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