静态站点生成 (SSG)
在架构中,我们提到主题在 Webpack 中运行。但请注意:这并不意味着它总是可以访问浏览器全局变量!主题构建了两次
- 在服务器端渲染期间,主题在一个名为React DOM Server的沙盒中编译。你可以将其视为一个“无头浏览器”,其中没有
window
或document
,只有 React。SSR 生成静态 HTML 页面。 - 在客户端渲染期间,主题被编译成 JavaScript,最终在浏览器中执行,因此它可以访问浏览器变量。
服务器端渲染和静态站点生成可能是不同的概念,但我们互换使用它们。
严格来说,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}</>;
}
import React from 'react';
export default function expensiveComp() {
- if ('production' === '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 文件。这与站点生成器(如Jekyll和Docusaurus v1)不同,在这些生成器中,所有文件都静态转换为标记,并通过链接到 <script>
标签的外部 JavaScript 添加交互性。如果你检查构建输出,你仍然会在 build/assets/js
下看到 JS 资源,这些才是 Docusaurus 的核心。
逃逸机制
如果你想在屏幕上渲染任何依赖浏览器 API 才能正常工作的动态内容,例如
你可能需要从 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 根本不更新)。
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
if (ExecutionEnvironment.canUseDOM) {
document.title = "I'm loaded!";
}