Gatsby 添加 React 组件完全指南：从内置 Link 到第三方组件库与 SSR 兼容实战

Gatsby 添加 React 组件完全指南：从内置 Link 到第三方组件库与 SSR 兼容实战

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

本指南以 Gatsby 官方文档 Adding React Components 为核心骨架，系统讲解如何在 Gatsby 站点中引入、组织和使用 React 组件（含第三方组件库），并深入剖析 Gatsby 构建时服务端渲染（SSR）对组件代码的约束——这是所有 Gatsby 开发者都会遇到的“window is not defined”类问题的根源所在。读完本文，你将掌握组件导入的规范做法、内置<Link>组件的性能增强机制、第三方组件与 Gatsby 插件的配合方式，以及规避浏览器全局变量构建报错的完整修复方案。

React 组件基础：可复用的 UI 构建单元

React 组件是预先构建好的元素或元素集合，用来将用户界面（UI）拆分成独立、可复用的部分。在 Gatsby 中，组件既可以是你自己编写的功能组件（functional components），也可以是来自 npm 生态的第三方组件，还可以是 Gatsby 官方提供的内置组件。

组件可以通过“props”（properties，属性）进行定制。props 可以是任意 JavaScript 数据类型，例如 Boolean、String 或 Object。以按钮组件为例：你可以在站点的不同页面上多次使用同一个 Button 组件，每次传入不同的标签文案或点击行为，这正是组件“一次编写、处处复用”的价值所在。

本指南聚焦于函数式组件（functional components）。如果你需要深入了解包括 class 组件在内的全部 React 组件写法，可以参考 React 官方文档（本文仅覆盖仓库内可直接验证的 Gatsby 实践内容）。

在 Gatsby 中导入 React 组件

在 Gatsby 中使用 React 组件，导入与使用方式与普通 React 应用完全一致。Gatsby 站点本身就是由 React 组件构成的：src/pages目录下的每个组件文件都会自动被编译为对应的静态页面。

与普通 React 应用不同的是，Gatsby 内置了一批带有额外性能增强功能的组件，其中最具代表性的是<Link>组件。下面是一个Contact页面使用 GatsbyLink的完整示例：

import React from "react" import { Link } from "gatsby" export default function Contact() { return ( <div> <Link to="/contact/">Contact</Link> </div> ) }

<Link>的性能秘密：源码级解读

与普通的<a>标签不同，Gatsby 的<Link>组件驱动着一项名为preloading（预加载）的关键性能特性。从源码 packages/gatsby-link/src/index.js 可以看到其核心机制：

1. 两阶段预加载：当<Link>组件进入用户视口时，Gatsby 通过浏览器的IntersectionObserverAPI 启动一个低优先级的页面资源请求；当鼠标悬停在链接上触发onMouseOver事件时，再将请求升级为高优先级，从而确保用户点击导航的瞬间页面资源已就绪。

2. 源码佐证：createIntersectionObserver函数（packages/gatsby-link/src/index.js#L21-L37）监听元素是否进入视口，并在handleRef中触发_prefetch()调用___loader.enqueue(newPathName)完成资源预取；___loader.hovering(...)则对应悬停时的高优先级升级。

3. 智能跳过当前页：_prefetch中有一个细节——如果预取路径与当前页面路径相同，则跳过预取，避免 Chrome 使用陈旧数据产生竞态条件。

4. 自动回退到<a>：isLocalLink函数（packages/gatsby-link/src/is-local-link.js）通过正则/^[a-zA-Z][a-zA-Z\d+\-.]*?:/判断链接是否为绝对地址。如果传给<Link>的是外部链接，组件会自动渲染为普通<a>标签；在开发环境下还会输出External link ... was detected in a Link component的警告。

因此，同站内部链接请使用<Link>（属性为to），外部链接仍使用<a href>。两者工作方式几乎相同，唯一区别是href变成了to。<Link>还额外支持activeClassName、activeStyle、partiallyActive等激活态定制属性（partiallyActive用于让/blog#hello-world这类带 hash 的 URL 也能匹配<Link to="/blog">）。

导入第三方组件与组件库

与纯 React 一样，Gatsby 同样支持第三方组件和库。你可以通过包管理器安装它们。官方示例倾向于使用 npm，因此下面的示例也以 npm 为准。

关键原则：

• 不要混用包管理器（如果用了 npm，就不要再用 yarn/pnpm 等其他工具管理同一项目）；
• 如果该库存在对应的 Gatsby 插件，应优先安装并使用插件——插件通常负责处理 SSR、webpack 配置等兼容性问题。

下面以 Material UI 为例，展示完整的三步接入流程。

第一步：安装插件及其依赖库

npm install gatsby-plugin-material-ui @material-ui/core

第二步：在gatsby-config.js的 plugins 数组中注册插件

module.exports = { plugins: [`gatsby-plugin-material-ui`], }

第三步：在页面源码中导入并使用组件库

import React from "react" // import my fancy third-party component import Button from "@material-ui/core/Button" export default function Home() { return ( <div> <p>This is my super awesome page made with Gatsby!</p> {/* use my fancy third-party component */} <Button variant="contained">Fancy button!</Button> </div> ) }

这个流程同样适用于绝大多数 React 生态组件库（如 styled-components、Emotion 等）：先查有无对应 Gatsby 插件，安装插件与库本体，注册插件，然后像普通 React 项目一样导入使用。

需要警惕的问题：SSR 对组件代码的约束

Gatsby 使用服务端渲染（SSR）来生成站点页面——你的 JSX 代码通常在浏览器加载页面之前就被编译执行。这意味着代码运行在 Node.js 环境而非浏览器环境，某些浏览器特性在编译期不可用，直接引用就会导致构建错误。

浏览器全局变量的误用

一些组件或代码会引用window、document、localStorage等浏览器全局对象。这些对象在构建期不存在，webpack 编译时会抛出如下错误：

WebpackError: ReferenceError: window is not defined

这是构建失败最常见的原因。关于 SSR 与浏览器 API 的完整解决方案，官方文档在从 Create React App 迁移到 Gatsby 中有专门章节（其中列出了window、document、localStorage、sessionStorage、navigator等常见需要保护的全局对象）。

修复思路有三种（详见 调试 HTML 构建）：

方案一：先判断window是否存在再使用

import * as React from "react" // Check if window is defined (so if in the browser or in node.js). const isBrowser = typeof window !== "undefined" export default function MyComponent() { let loggedIn = false if (isBrowser) { window.localStorage.getItem("isLoggedIn") === "true" } return <div>Am I logged in? {loggedIn}</div> }

方案二（class 组件）：把浏览器全局引用移入componentDidMount生命周期

import React, { Component } from "react" class MyComponent extends Component { componentDidMount() { // code that references the browser global window.alert("This won't break the build") } render() { return ( <div> <p>Component</p> </div> ) } }

方案三（函数组件）：把浏览器全局引用移入useEffecthook

import React from "react" const Foo = () => { React.useEffect(() => { window.alert("This won't break the build") }) return <span>Bar</span> } export default Foo

componentDidMount与useEffect都只在浏览器端执行，从而保证构建期不会引用到未定义的全局对象。

模块加载中的window引用问题

如果你是在模块顶层直接require一个依赖window的模块，同样会报错：

// Requiring a function causes an error during builds // as the code tries to reference window const module = require("module") // Error // Wrap the require in check for window if (typeof window !== `undefined`) { const module = require("module") }

如果该模块必须存在才能继续运行，可以使用三元表达式：

const module = typeof window !== `undefined` ? require("module") : null

修补不兼容 SSR 的第三方模块

有些 npm 包在顶层就假设window一定存在（例如部分路由库），这类包必须被打补丁才能通过构建。除了向上游提 issue 等待修复外，Gatsby 提供了两种即时可用的办法（详见 调试 HTML 构建文档 中的 “Fixing third-party modules” 章节）：

办法一：通过 webpack 配置将问题模块替换为空模块

在项目根目录的gatsby-node.js中自定义 webpack 配置，仅对 HTML 构建阶段生效：

exports.onCreateWebpackConfig = ({ stage, loaders, actions }) => { if (stage === "build-html" || stage === "develop-html") { actions.setWebpackConfig({ module: { rules: [ { test: /bad-module/, use: loaders.null(), }, ], }, }) } }

loaders.null()会把匹配bad-module的模块替换为空实现，服务端渲染时不再真正加载它。

办法二：使用动态加载方案

借助loadable-components之类的库，让使用window的模块只在客户端动态加载，SSR 阶段完全不触碰它。

在开发模式下提前暴露 SSR 问题：DEV_SSR 标志

SSR 相关的 bug 不必等到gatsby build才暴露。Gatsby 提供了DEV_SSR实验标志：开启后，gatsby develop会在页面整页刷新（如 Ctrl + R / F5）时执行服务端渲染，从而在开发阶段就发现 SSR 兼容性问题。在gatsby-config.js中配置：

module.exports = { flags: { DEV_SSR: true }, plugins: [...] }

在仓库源码中，DEV_SSR标志由 packages/gatsby/src/utils/flags.ts 定义，并驱动 packages/gatsby/src/utils/dev-ssr/render-dev-html.ts 等开发期 SSR 渲染逻辑——这是该功能真实存在并生效的直接源码证据。

没有 SSR 支持的组件怎么办

服务端渲染意味着页面和内容由 Node.js 服务器预先构建好，再发送给浏览器直接使用——页面在到达用户之前就已经构建完成。Gatsby 在构建期完成 SSR，这意味着浏览器拿到的代码已经运行过一遍、用于生成页面内容，但这并不意味着站点不能有动态页面。

部分 React 组件本身不提供 SSR 支持（例如依赖浏览器 DOM 的组件），此时你可能需要自己为组件补充 SSR 兼容处理，手段正是上文所述的全局变量保护、生命周期/hook 迁移、webpack 空模块替换或客户端动态加载。在 Gatsby 中，这类“客户端专属”逻辑还可以通过gatsby-browser.js与gatsby-ssr.js成对配置来区分浏览器端与服务端行为（详见从 Create React App 迁移指南 中关于wrapRootElement的示例）。

实战小结：组件接入决策速查

通过以上流程，你既可以像普通 React 项目一样自由组织组件，又能充分享受 Gatsby 构建期 SSR 与内置组件的性能红利，同时避免掉进“浏览器全局变量在构建期未定义”这一最常见的坑。仓库中的 adding-react-components.md、gatsby-link.md、debugging-html-builds.md 三份文档互为补充，配合 packages/gatsby-link/src/index.js 源码，即可获得从实践到原理的完整认知闭环。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby