哪些情况下Gatsby的onRenderBody钩子不会被执行？

AI 小北

2026-10-17

问题原因及解决方法

首先可以确认gatsby-ssr.js文件已经被Gatsby正常加载，问题出在onRenderBody钩子没有被正确识别或触发，按照以下优先级排查即可：

检查钩子导出规则：Gatsby会静态扫描gatsby-ssr.js的顶层命名导出来识别SSR钩子，必须满足两个要求：
- 钩子名拼写完全正确，为驼峰格式onRenderBody，不能有大小写错误或拼写偏差
- 必须是文件顶层的命名导出，不能嵌套在条件判断、函数、块级作用域内部，也不能使用默认导出
  错误写法示例：
```
// 错误：嵌套在条件内，静态扫描无法识别
if (process.env.NODE_ENV === 'production') {
  export const onRenderBody = () => {
    console.log('ON RENDER BODY')
  }
}

// 错误：使用默认导出
export default onRenderBody
```
正确写法示例：
```
// 顶层命名导出
export const onRenderBody = () => {
  console.log('ON RENDER BODY')
}
```
检查页面SSR配置：Gatsby v4及以上版本支持页面级关闭SSR，如果所有页面组件中都配置了export const config = { ssr: false }，SSR流程会被跳过，自然不会触发onRenderBody钩子，删除对应页面的该配置即可。
检查全局SSR开关：
- 确认gatsby-config.js中没有安装gatsby-plugin-disable-ssr这类全局关闭SSR的插件
- 开发模式下如果需要触发钩子，可以在gatsby-config.js的flags配置中添加DEV_SSR: true，否则gatsby develop默认走客户端渲染，不会触发SSR钩子。