Gatsby+TypeScript读取本地JSON报错，求解决及数据获取原理

核心原理 #

Gatsby读取本地JSON文件依赖两个核心插件的协作：

1. gatsby-source-filesystem：扫描指定目录，为每个文件生成File数据节点，记录文件路径、名称等元信息。
2. gatsby-transformer-json：监听File节点，识别.json后缀文件，将其内容解析为可通过GraphQL查询的节点：
   • 若JSON是对象结构，生成单个[文件名首字母大写]Json节点（如navigationJson）
   • 若JSON是数组结构，生成all[文件名首字母大写]Json集合节点（如allNavigationJson），数组中的每个元素对应一个子节点
3. 在TypeScript环境中，Gatsby会自动生成GraphQL类型定义，也可通过gatsby-plugin-graphql-codegen增强类型校验能力。

问题排查与解决步骤 #

1. 验证gatsby-config.ts插件配置 #

确保两个插件配置正确，尤其注意路径的准确性：

export default {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `data`,
        path: `${__dirname}/data/`, // 用__dirname确保绝对路径，避免相对路径错误
      },
    },
    `gatsby-transformer-json`,
  ],
}

• 注意TypeScript配置文件需用export default导出配置对象，而非CommonJS的module.exports。

2. 修正GraphQL查询字段名 #

你当前使用的allNavigationLinksJson字段名错误——Gatsby的节点名是基于文件名生成的，而非自定义命名。对于navigation.json（数组结构），正确的查询字段应为allNavigationJson。

正确的查询示例：

query NavigationQuery {
  allNavigationJson {
    nodes {
      title
      href
    }
  }
}

可通过localhost:8000/___graphql的Explorer面板，搜索all开头的字段，确认生成的节点名称。

3. 处理gatsby-config.ts的格式提示 #

Gatsby对TypeScript配置文件的支持需要项目TS环境正常：

• 确认已安装gatsby-plugin-typescript（Gatsby v4+已内置TS支持，可省略）
• 若提示转为gatsby-config.js，可临时改用CommonJS格式的配置文件测试：

  module.exports = {
    plugins: [
      {
        resolve: `gatsby-source-filesystem`,
        options: {
          name: `data`,
          path: `${__dirname}/data/`,
        },
      },
      `gatsby-transformer-json`,
    ],
  }
  

  测试数据能否正常读取，排除TS配置的影响。

4. 彻底清理缓存并重启服务 #

执行以下命令彻底清除Gatsby缓存，确保重新扫描文件生成节点：

gatsby clean
gatsby develop

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