配置gatsby-source-filesystem查询单个JSON文件及页面创建故障排查

看起来你在使用gatsby-transformer-json处理外链列表时遇到了查询失败的问题，大概率是gatsby-source-filesystem的配置细节没到位，我来一步步帮你排查解决：

1. 先确认核心插件的安装与配置 #

首先得确保你已经安装了必要的两个插件，在项目根目录执行：

npm install gatsby-transformer-json gatsby-source-filesystem
# 或者用yarn
yarn add gatsby-transformer-json gatsby-source-filesystem

然后在gatsby-config.js里正确配置gatsby-source-filesystem，关键是指向存放links.json的目录，而不是文件本身。比如你的links.json放在src/data文件夹下，配置应该是这样：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `data`,
        path: `${__dirname}/src/data/`, // 这里是目录路径，不是文件路径！
      },
    },
    `gatsby-transformer-json`, // 确保这个插件也在配置列表里
  ],
};

这里最容易踩坑的就是把path写成了links.json的具体文件路径，一定要指向目录！

2. 检查你的links.json结构 #

你的查询语句{ allLinksJson { edges { node { value } } } }对应的是数组类型的JSON文件，比如你的links.json应该是这种格式：

[
  { "value": "https://example.com" },
  { "value": "https://test-site.com" },
  { "value": "https://demo-page.com" }
]

如果你的JSON是对象包裹数组的结构（比如{ "links": [...] }），那查询语句就要调整，比如：

{
  allLinksJson {
    edges {
      node {
        links {
          value
        }
      }
    }
  }
}

所以先确认你的JSON结构和查询语句匹配。

3. 用GraphiQL验证查询是否有效 #

启动Gatsby开发服务器后，访问http://localhost:8000/___graphql，在左侧输入你的查询语句，点击执行按钮：

• 如果能返回预期的value数据，说明配置没问题，接下来可以写生成页面的代码
• 如果返回空数组或者报错，那回到第一步检查配置路径、JSON格式，或者重启开发服务器试试

4. 编写生成页面的代码（gatsby-node.js） #

确认查询能拿到数据后，在项目根目录创建gatsby-node.js，用createPages API生成每个链接的页面：

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

  // 执行查询获取所有链接数据
  const queryResult = await graphql(`
    query GetAllLinks {
      allLinksJson {
        edges {
          node {
            value
            id # Gatsby自动生成的唯一ID，用来做页面路径的slug
          }
        }
      }
    }
  `);

  // 如果查询出错，直接抛出错误终止流程
  if (queryResult.errors) {
    throw queryResult.errors;
  }

  // 遍历每个链接，创建对应的页面
  queryResult.data.allLinksJson.edges.forEach(({ node }) => {
    createPage({
      // 自定义页面路径，比如用ID作为slug
      path: `/links/${node.id}`,
      // 指向你的页面模板组件，需要自己创建这个文件
      component: require.resolve("./src/templates/link-template.js"),
      // 传递给模板的数据，模板里可以通过pageContext获取
      context: {
        linkUrl: node.value,
        linkId: node.id,
      },
    });
  });
};

5. 创建页面模板组件 #

在src/templates目录下创建link-template.js，用来渲染每个链接页面：

import React from "react";

export default function LinkTemplate({ pageContext }) {
  const { linkUrl } = pageContext;
  return (
    <div className="link-page">
      <h2>External Link</h2>
      <a 
        href={linkUrl} 
        target="_blank" 
        rel="noopener noreferrer"
      >
        Visit: {linkUrl}
      </a>
    </div>
  );
}

最后排查小技巧 #

• 如果还是查不到数据，检查links.json有没有语法错误（比如少了逗号、引号不匹配）
• 确认gatsby-config.js里的插件顺序，虽然Gatsby会自动处理依赖顺序，但如果有多个source配置，确保目标目录的配置是正确的
• 重启开发服务器，有时候配置修改后需要重启才能生效

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