Gatsby使用getServerData()的SSR本地正常但Netlify部署异常

我使用Gatsby 4.25.0、Node 14.20.1和React 18.1.0构建了一个示例站点并部署在Netlify上。站点包含两个页面：

• /test.js：从API获取犬种列表，渲染为链接列表：

  // test.js
  <ul>
    {dogBreeds.map((breed, idx) => (
      <li key={idx}>
        <Link to={`/dogs/${breed}`}>{breed}</Link>
      </li>
    ))}
  </ul>
  

• 动态页面/dogs/[breed].js：使用getServerData()从路由参数获取犬种，调用API获取对应图片展示：

  export async function getServerData(context) {
    const { breed } = context.params
    try {
      const res = await fetch(`https://dog.ceo/api/breed/${breed}/images/random`)
      const data = await res.json()
  
      console.log(`data from the getServerData function: ${data}`)
  
      if (!res.ok) {
        throw new Error(`Response failed`)
      }
  
      return {
        props: {
          breed,
          imageUrl: data.message,
        },
      }
    } catch (error) {
      return {
        status: 200,
        headers: {},
        props: {},
      }
    }
  }
  

本地运行时一切正常，可通过链接跳转到动态路由并正常显示图片。但在Netlify上出现以下问题：

• 鼠标悬停在test.js的链接上时，控制台出现来自loader.js和prefetch.js的404错误
• 点击犬种链接会跳转到404页面

已配置gatsby-plugin-netlify和@netlify/plugin-gatsby插件。

针对Netlify上Gatsby 4动态路由SSR的404问题，可按以下步骤排查修复：

1. 确保@netlify/plugin-gatsby版本兼容 #

Gatsby 4对Netlify插件有特定版本要求，旧版本可能不支持其SSR特性。执行命令更新到最新兼容版本：

npm update @netlify/plugin-gatsby
# 或使用yarn
yarn upgrade @netlify/plugin-gatsby

2. 检查netlify.toml配置 #

确认插件已正确配置在netlify.toml中，避免语法错误：

[[plugins]]
package = "@netlify/plugin-gatsby"

# 可选：若需指定Gatsby版本，可添加以下配置
# [plugins.inputs]
# gatsbyVersion = "4.25.0"

3. 临时禁用Link预取排查 #

Gatsby的Link组件默认开启悬停预取，若Netlify上预取路径映射错误会触发404。临时添加prefetch={false}属性测试：

<Link to={`/dogs/${breed}`} prefetch={false}>{breed}</Link>

如果点击链接能正常访问动态页面，说明预取逻辑存在配置问题，需进一步检查插件生成的预取路由映射。

4. 清除Netlify缓存并重新部署 #

Netlify的缓存可能残留旧构建产物导致异常，在Netlify控制台的部署页面选择Clear cache and deploy site，强制重新构建。

5. 检查部署日志 #

查看Netlify部署日志，确认：

• @netlify/plugin-gatsby是否正常运行，是否生成了.netlify/functions-internal目录下的SSR函数
• 构建过程中是否有报错信息（如依赖缺失、API调用失败等）

6. 统一Node版本 #

确保Netlify构建环境使用的Node版本与本地一致（14.20.1），可在netlify.toml中指定：

[build.environment]
NODE_VERSION = "14.20.1"

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