Gatsby部署GitHub Pages后useStaticQuery失效及数据提取问题

一、无需重构：让useStaticQuery在GitHub Pages正常工作的排查点 #

• 配置路径前缀：如果你的GitHub Pages部署在子路径（比如https://your-username.github.io/your-repo/），必须在gatsby-config.js中添加路径前缀配置：

  module.exports = {
    pathPrefix: "/your-repo",
    // 其他原有配置...
  }
  

  构建时需带上--prefix-paths参数：

  gatsby build --prefix-paths
  

  这是最常见的触发原因——本地开发无路径前缀限制，部署后路径不匹配导致查询数据无法正常映射。
• 校验siteMetadata一致性：确认本地与部署环境的gatsby-config.js中，siteMetadata下的appModules配置完全一致，避免部署时遗漏或配置错误。
• 清除缓存：GitHub Pages可能留存旧构建缓存，可在仓库的Settings -> Pages页面手动触发重新部署，或访问页面时按Ctrl+Shift+R强制刷新浏览器缓存。

二、StaticQuery结合useEffect的用法 #

要在useEffect中使用StaticQuery返回的数据，需将副作用逻辑与查询数据的作用域对齐，以下是两种可行方案：

方案1：封装内部组件接收数据 #

将Header的渲染逻辑拆分为内部组件，通过props接收StaticQuery的数据，在内部组件中编写useEffect：

import { graphql, Link, StaticQuery } from "gatsby"
import React, { useEffect } from "react"
import { NavbarBrand } from "reactstrap"

// 内部组件：接收查询数据并处理副作用
const HeaderContent = ({ data }) => {
  useEffect(() => {
    console.log(data.site.siteMetadata.appModules)
    // 在这里编写你的副作用逻辑
  }, [data])

  return (
    <header>
      <NavbarBrand href="/">
        <img className="m-0" src="/doc/images/img" alt={data.site.siteMetadata.title} />
      </NavbarBrand>
      <div>
        {data.site.siteMetadata.appModules.map((appModule, index) => (
          <Link key={index} to={`/${appModule}`}>
            {appModule} 
          </Link>
        ))}
      </div>
    </header>
  )
}

export default () => {
  return (
    <StaticQuery
      query={graphql`
        query {
          site {
            siteMetadata {
              title
              appModules
            }
          }
        }
      `}
      render={data => <HeaderContent data={data} />}
    />
  )
}

方案2：用状态存储查询数据 #

通过useState将StaticQuery的数据存入组件状态，再在useEffect中依赖该状态执行逻辑：

import { graphql, Link, StaticQuery } from "gatsby"
import React, { useState, useEffect } from "react"
import { NavbarBrand } from "reactstrap"

export default () => {
  const [siteData, setSiteData] = useState(null)

  useEffect(() => {
    if (siteData) {
      console.log(siteData.site.siteMetadata.appModules)
      // 在这里编写你的副作用逻辑
    }
  }, [siteData])

  return (
    <StaticQuery
      query={graphql`
        query {
          site {
            siteMetadata {
              title
              appModules
            }
          }
        }
      `}
      render={data => {
        setSiteData(data)
        return (
          <header>
            <NavbarBrand href="/">
              <img className="m-0" src="/doc/images/img" alt={data.site.siteMetadata.title} />
            </NavbarBrand>
            <div>
              {data.site.siteMetadata.appModules.map((appModule, index) => (
                <Link key={index} to={`/${appModule}`}>
                  {appModule} 
                </Link>
              ))}
            </div>
          </header>
        )
      }}
    />
  )
}

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