Gatsby项目如何正确加载索引文件？从CRA迁移后gatsby build报错问询

核心错误点 #

• wrapRootElement 配置位置错误：Gatsby 规定该 API 必须定义在项目根目录的 gatsby-browser.js（客户端渲染生效）和 gatsby-ssr.js（构建/服务端渲染生效）文件中，不能写在 src/pages/index.js 页面文件内。
• wrapRootElement 返回值不符合规范：你当前的代码通过逗号运算符最终返回的是 document.querySelector('#app') DOM 节点，而 Gatsby 要求该 API 仅需返回包装后的 React 元素即可，挂载逻辑由 Gatsby 内部处理，不需要手动指定挂载容器，这是和 CRA 手动调用 ReactDOM.render 最核心的差异。
• src/pages/index.js 职责错误：该路径是 Gatsby 约定的首页路由文件，需要默认导出一个 React 组件作为首页内容，不应该存放全局根组件包装逻辑。
• 多余的根 Router 组件：Gatsby 已内置路由处理能力，不需要手动在根位置挂载自定义 Router 容器。

具体修改步骤 #

1. 清理 src/pages/index.js，仅保留首页UI组件作为默认导出，示例如下：

// src/pages/index.js
export default function Home() {
  return <div>你的首页内容</div>
}

2. 在项目根目录（和 gatsby-config.js 同级）新建 gatsby-browser.js 和 gatsby-ssr.js 两个文件，两份文件写入完全相同的配置：

// gatsby-browser.js / gatsby-ssr.js 通用代码
import Store from './src/store';
import Errors from './src/components/Errors';
import HtmlHead from './src/components/HtmlHead';
import { Provider } from 'react-redux';
import Intl from './src/components/Intl';

// 全局初始化逻辑放在此处
someSetup();

export const wrapRootElement = ({ element }) => {
  // 直接返回包装后的元素，element参数为Gatsby传入的当前页面组件
  return (
    <Errors>
      <>
        <HtmlHead title={`${getPageTitle()}`} />
        <Provider store={Store}>
          <Intl>
            {element}
          </Intl>
        </Provider>
      </>
    </Errors>
  );
};

注意：如果你的全局初始化逻辑或者组件中用到了 window、document 等浏览器独有的API，需要加 typeof window !== 'undefined' 逻辑判断，避免构建阶段执行时报错。

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