跳到主要内容
版本:3.8.1

静态站点生成 (SSG)

架构中,我们提到主题在 Webpack 中运行。但请注意:这并不意味着它总是可以访问浏览器全局变量!主题构建了两次

  • 服务器端渲染期间,主题在一个名为React DOM Server的沙盒中编译。你可以将其视为一个“无头浏览器”,其中没有 windowdocument,只有 React。SSR 生成静态 HTML 页面。
  • 客户端渲染期间,主题被编译成 JavaScript,最终在浏览器中执行,因此它可以访问浏览器变量。
SSR 还是 SSG?

服务器端渲染静态站点生成可能是不同的概念,但我们互换使用它们。

严格来说,Docusaurus 是一个静态站点生成器,因为没有服务器端运行时——我们静态渲染到部署在 CDN 上的 HTML 文件,而不是在每次请求时动态预渲染。这与Next.js的工作模式不同。

因此,尽管你可能知道不要访问 Node 全局变量,例如 process或者可以吗?)或 'fs' 模块,但你也不能随意访问浏览器全局变量。

import React from 'react';

export default function WhereAmI() {
return <span>{window.location.href}</span>;
}

这看起来像是地道的 React 代码,但如果你运行 docusaurus build,你将会收到一个错误

ReferenceError: window is not defined

这是因为在服务器端渲染期间,Docusaurus 应用程序实际上并未在浏览器中运行,它不知道 window 是什么。

process.env.NODE_ENV 呢?

“不使用 Node 全局变量”规则的一个例外是 process.env.NODE_ENV。实际上,你可以在 React 中使用它,因为 Webpack 将此变量注入为全局变量

import React from 'react';

export default function expensiveComp() {
if (process.env.NODE_ENV === 'development') {
return <>This component is not shown in development</>;
}
const res = someExpensiveOperationThatLastsALongTime();
return <>{res}</>;
}

在 Webpack 构建期间,process.env.NODE_ENV 将被替换为值,可以是 'development''production'。死代码消除后,你将获得不同的构建结果

import React from 'react';

export default function expensiveComp() {
if ('development' === 'development') {
+ return <>This component is not shown in development</>;
}
- const res = someExpensiveOperationThatLastsALongTime();
- return <>{res}</>;
}

理解 SSR

React 不仅仅是一个动态 UI 运行时——它还是一个模板引擎。因为 Docusaurus 站点主要包含静态内容,它应该能够在没有任何 JavaScript(React 运行其中)的情况下工作,而只有纯 HTML/CSS。这就是服务器端渲染所提供的:将你的 React 代码静态渲染成 HTML,不包含任何动态内容。HTML 文件没有客户端状态的概念(它纯粹是标记),因此它不应该依赖于浏览器 API。

当访问 URL 时,这些 HTML 文件首先到达用户的浏览器屏幕(参阅路由)。之后,浏览器会获取并运行其他 JS 代码,以提供站点的“动态”部分——任何用 JavaScript 实现的功能。然而,在此之前,页面的主要内容已经可见,从而加快了加载速度。

在仅 CSR 的应用程序中,所有 DOM 元素都是在客户端使用 React 生成的,HTML 文件只包含一个根元素供 React 挂载 DOM;而在 SSR 中,React 已经面对一个完全构建好的 HTML 页面,它只需要将其模型中的虚拟 DOM 与 DOM 元素关联起来。这一步被称为“注水”(hydration)。在 React 注水静态标记后,应用程序就开始像任何正常的 React 应用程序一样工作。

请注意,Docusaurus 最终是一个单页应用程序,因此静态站点生成只是一种优化(渐进增强,正如它所说的),但我们的功能并不完全依赖于这些 HTML 文件。这与站点生成器(如JekyllDocusaurus v1)不同,在这些生成器中,所有文件都静态转换为标记,并通过链接到 <script> 标签的外部 JavaScript 添加交互性。如果你检查构建输出,你仍然会在 build/assets/js 下看到 JS 资源,这些才是 Docusaurus 的核心。

逃逸机制

如果你想在屏幕上渲染任何依赖浏览器 API 才能正常工作的动态内容,例如

  • 我们的实时代码块,它在浏览器的 JS 运行时中运行
  • 我们的主题图像,它可以检测用户的配色方案以显示不同的图像
  • 我们调试面板的 JSON 查看器,它使用 window 全局变量进行样式设置

你可能需要从 SSR 中逃逸,因为静态 HTML 在不知道客户端状态的情况下无法显示任何有用的内容。

警告

第一次客户端渲染产生与服务器端渲染完全相同的 DOM 结构非常重要,否则 React 会将虚拟 DOM 与错误的 DOM 元素关联起来。

因此,if (typeof window !== 'undefined) {/* render something */} 的天真尝试无法作为浏览器与服务器检测的合适方法,因为第一次客户端渲染会立即渲染出与服务器生成内容不同的标记。

你可以在再注水(Rehydration)的陷阱中了解更多关于这个陷阱的信息。

我们提供了几种更可靠的方法来逃逸 SSR。

<BrowserOnly>

如果你需要只在浏览器中渲染某个组件(例如,因为该组件完全依赖于浏览器特性才能正常运行),一种常见的方法是使用<BrowserOnly>包装你的组件,以确保它在 SSR 期间不可见,并且只在 CSR 中渲染。

import BrowserOnly from '@docusaurus/BrowserOnly';

function MyComponent(props) {
return (
<BrowserOnly fallback={<div>Loading...</div>}>
{() => {
const LibComponent =
require('some-lib-that-accesses-window').LibComponent;
return <LibComponent {...props} />;
}}
</BrowserOnly>
);
}

重要的是要认识到 <BrowserOnly> 的子代不是 JSX 元素,而是一个返回元素的函数。这是一个设计决策。考虑以下代码

import BrowserOnly from '@docusaurus/BrowserOnly';

function MyComponent() {
return (
<BrowserOnly>
{/* DON'T DO THIS - doesn't actually work */}
<span>page url = {window.location.href}</span>
</BrowserOnly>
);
}

虽然你可能期望 BrowserOnly 在服务器端渲染期间隐藏其子代,但它实际上不能。当 React 渲染器尝试渲染这个 JSX 树时,它会把 {window.location.href} 变量看作这个树的一个节点并尝试渲染它,即使它实际上没有被使用!使用函数确保我们只在需要时才让渲染器看到仅限浏览器的组件。

useIsBrowser

你也可以使用 useIsBrowser() Hook 来测试组件当前是否在浏览器环境中。它在 SSR 中返回 false,在第一次客户端渲染后返回 true。如果你只需要在客户端执行某些条件操作,而不是渲染一个完全不同的 UI,请使用此 Hook。

import useIsBrowser from '@docusaurus/useIsBrowser';

function MyComponent() {
const isBrowser = useIsBrowser();
const location = isBrowser ? window.location.href : 'fetching location...';
return <span>{location}</span>;
}

useEffect

最后,你可以将逻辑放在 useEffect() 中,以将其执行延迟到第一次 CSR 之后。如果你只执行副作用而不从客户端状态获取数据,这是最合适的方法。

function MyComponent() {
useEffect(() => {
// Only logged in the browser console; nothing is logged during server-side rendering
console.log("I'm now in the browser");
}, []);
return <span>Some content...</span>;
}

ExecutionEnvironment

ExecutionEnvironment 命名空间包含多个值,canUseDOM 是检测浏览器环境的有效方法。

请注意,它在底层本质上是检查 typeof window !== 'undefined',因此你不应该将其用于渲染相关的逻辑,而只用于命令式代码,例如通过发送 Web 请求响应用户输入,或动态导入库(其中 DOM 根本不更新)。

a-client-module.js
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
document.title = "I'm loaded!";
}