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 可以看到其核心机制两阶段预加载当Link组件进入用户视口时Gatsby 通过浏览器的IntersectionObserverAPI 启动一个低优先级的页面资源请求当鼠标悬停在链接上触发onMouseOver事件时再将请求升级为高优先级从而确保用户点击导航的瞬间页面资源已就绪。源码佐证createIntersectionObserver函数packages/gatsby-link/src/index.js#L21-L37监听元素是否进入视口并在handleRef中触发_prefetch()调用___loader.enqueue(newPathName)完成资源预取___loader.hovering(...)则对应悬停时的高优先级升级。智能跳过当前页_prefetch中有一个细节——如果预取路径与当前页面路径相同则跳过预取避免 Chrome 使用陈旧数据产生竞态条件。自动回退到aisLocalLink函数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 pThis is my super awesome page made with Gatsby!/p {/* use my fancy third-party component */} Button variantcontainedFancy 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 divAm 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 wont break the build) } render() { return ( div pComponent/p /div ) } }方案三函数组件把浏览器全局引用移入useEffecthookimport React from react const Foo () { React.useEffect(() { window.alert(This wont break the build) }) return spanBar/span } export default FoocomponentDidMount与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的示例。实战小结组件接入决策速查场景推荐做法依据同站页面跳转使用内置Link to...享受预加载性能优化gatsby-link.md外部链接使用普通a href同上Link会自动降级为a并发出警告程序化导航如表单提交后跳转使用navigate(/path/)Link无法处理非点击型导航引入第三方组件库npm install插件库本体 → 注册到gatsby-config.js→ 页面内导入使用本文第三部分示例组件引用了window等全局对象用typeof window ! undefined保护或移入componentDidMount/useEffectdebugging-html-builds.md第三方模块强依赖浏览器全局webpackloaders.null()空替换或客户端动态加载同上开发期提前发现 SSR 问题开启flags: { DEV_SSR: true }debugging-html-builds.md通过以上流程你既可以像普通 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考