已创建about.js文件但Gatsby页面无法加载的问题排查

问题描述 #

我是React和Gatsby新手，跟着Gatsby官方教程学习到Part 2时遇到问题：按教程创建了about.js文件并编写基础组件，仅修改少量文本内容，但访问http://localhost:8000/about/时出现404错误（进入Gatsby开发版404页面），且页面底部已识别出该/about/路径。尝试重启gatsby develop后问题依然存在。

相关代码 #

首页（index.js） #

import * as React from 'react'
import { Link } from 'gatsby'

const IndexPage = () => {
  return (
    <main>
      <h1>This is my header</h1>
      <p>This is my paragraph, WOWZA!</p>  
      <Link to='/about'>About</Link>
    </main>
  )
}

export default IndexPage

关于页（about.js） #

import * as React from 'react'
import { Link } from 'gatsby'

const AboutPage = () => {
  return (
    <main>
      <h1>About Me</h1>
      <Link to="/">Back to Home</Link>
      <p>Hi there! I'm the proud creator of this site, which I built with Gatsby.</p>
    </main>
  )
}

export const Head = () => <title>About Me</title>

export default AboutPage

相关截图 #

• 首页截图：
• 404页面截图：

原因分析及解决办法 #

1. 文件放置路径错误 #

Gatsby会自动将src/pages/目录下的文件生成为对应路由页面，如果about.js没有放在这个目录下，Gatsby无法识别并生成/about/路由。

• 检查文件路径：确保about.js位于项目根目录的src/pages/文件夹内，正确路径为src/pages/about.js。
• 如果文件位置错误，将其移动到src/pages/目录后，重启gatsby develop即可。

2. 缓存残留问题 #

Gatsby的缓存可能残留旧数据，导致页面未正确重建。执行以下命令清理缓存并重新启动开发服务器：

gatsby clean
gatsby develop

该命令会删除.cache和public文件夹，强制Gatsby重新构建所有页面资源。

3. 路由大小写不匹配 #

Gatsby开发环境的路由区分大小写，确保访问的路径http://localhost:8000/about/与Link组件中的to='/about'完全一致（注意小写的about），避免因大小写差异导致的404。

4. 版本兼容性问题 #

如果使用的是较旧版本的Gatsby，export const Head的写法可能不被支持（该写法适用于Gatsby v4及以上版本）。可以通过以下命令查看当前Gatsby版本：

gatsby --version

若版本过低，建议升级到最新稳定版，或对照对应版本的官方教程调整页面头部的写法。

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