React19.3的use(browser)怎么用？何时该跳过服务端渲染？

图 0：React 19.3 use(browser()) 服务端与客户端分流示意图

一、为什么需要 use(browser)？

在服务端渲染（SSR）和流式 HTML 架构中，一个长期困扰开发者的痛点是：部分组件天然必须依赖浏览器环境（如读取 localStorage、获取屏幕尺寸 window.innerWidth、读取设备当前本地时区，或初始化 Canvas 图表与富文本编辑器）。

在此前，社区通常只能通过两类变通手段跳过服务端渲染，但它们都伴随明显代价：

• typeof window !== 'undefined' 条件判断：在服务端渲染返回空或占位符，但在浏览器端首次渲染时直接读取真实值。这会导致服务端输出的 HTML 与浏览器首次执行生成的虚拟 DOM 树不一致，触发严重的 Hydration Mismatch（水合不匹配）警告，甚至导致整个子树被丢弃并重绘。
• useEffect + hasMounted 状态标记：先在组件中定义 const [mounted, setMounted] = useState(false)，在 useEffect 中将其置为 true。这种方式能规避水合错误，但它强制触发两次客户端渲染，必然产生肉眼可见的界面闪烁（Layout Shift / FOUC），并增加了多余的样板代码。

React 19.3 引入的 browser() 正式弥补了这一空缺。它是 React 运行时原生支持的跳过服务端渲染规范，直接融入了 React 的 Suspense 机制，彻底杜绝了水合冲突与无谓的双重渲染。

二、use(browser) 的具体用法与代码实现

browser() 由 react-dom 模块导出，在组件中使用时将其传入 React 原生 use() 函数中：use(browser(reason))。

1. 关键书写步骤

1. 声明客户端组件：在使用该 API 的文件顶部添加 'use client' 指令。
2. 从对应包导入：从 react 中导入 use 和 Suspense，从 react-dom 中导入 browser。
3. 在组件主体中调用：在读取任何浏览器独有 API 之前，调用 use(browser('说明文字'))。参数为一个简短字符串，描述组件为何需要浏览器环境。
4. 父层包裹 Suspense：使用该组件的父级必须提供 <Suspense fallback={...}> 降级边界。

图 1：使用 use(browser) 规避 SSR 的四步标准范式

2. 典型实战范式：读取浏览器本地草稿

以下示例展示一个自动读取浏览器 localStorage 本地草稿的输入框。在服务端渲染时它会自动回退到骨架屏，到达浏览器后再直接读取本地数据，全程无需任何 useEffect。

'use client';

import { Suspense, use } from 'react';
import { browser } from 'react-dom';

// 1. 仅在客户端完整渲染的业务组件
function ArticleDraftEditor() {
  // 在服务端直接挂起并命中外层 Suspense；在浏览器注水时继续向下执行
  use(browser('编辑器需读取 localStorage 恢复上次未保存的草稿'));

  // 安全读取浏览器专属对象，完全不会发生 Hydration Mismatch
  const savedDraft = localStorage.getItem('article_draft') ?? '';

  return (
    <div className="editor-box">
      <label htmlFor="draft-content">正文草稿：</label>
      <textarea
        id="draft-content"
        defaultValue={savedDraft}
        placeholder="请输入文章内容..."
      />
    </div>
  );
}

// 2. 父级组件负责提供合理的 Fallback 骨架
export default function EditorPage() {
  return (
    <section className="page-wrapper">
      <h2>文章起草</h2>
      <Suspense fallback={<div className="skeleton-editor">正在加载本地草稿...</div>}>
        <ArticleDraftEditor />
      </Suspense>
    </section>
  );
}

三、运行原理：服务端挂起与客户端注水

理解 use(browser()) 的核心在于认识 React 19 的 Suspense 生命周期处理：

图 2：use(browser) 核心挂起与注水生命周期

这套机制的精妙之处在于：服务端与客户端之间的“契约”完全统一到了 Suspense fallback。

• 在服务端，React 明确知道该组件当前不可渲染，因而不会试图执行会引发报错的 window 代码，而是合法地输出 fallback 标记。
• 在客户端水合之初，React 校验的是当前屏幕上的 fallback 标记与服务端返回的一致性，水合顺利通过；紧接着，browser() 在客户端立即可用，触发该组件的正常挂载渲染。因此既不会出现水合崩溃，也不存在由 useState(false) 引起的二次被动重绘。

四、方案对比：三种跳过 SSR 方式的关键差异

为了让技术选型更加明确，我们将 use(browser) 与既往的常见做法在一致条件下进行横向对比：

图 3：三种跳过 SSR 实现方案横向对比矩阵

五、何时该跳过服务端渲染？

虽然 use(browser) 使得跳过 SSR 的开发体验极为平滑，但这并不意味着应该滥用。服务端渲染的核心价值在于首屏渲染速度（FCP）与搜索引擎爬虫抓取（SEO）。

开发团队应当根据以下具体判定标准，有理有据地决定是否跳过服务端渲染：

图 4：组件是否应当跳过 SSR 的系统判定逻辑

适合跳过 SSR 的典型场景

1. 纯硬件与媒体交互组件： 调用 navigator.mediaDevices.getUserMedia 的视频捕获组件、WebRTC 实时通讯、读取传感器陀螺仪数据的 3D 交互场景。服务端无法模拟硬件设备句柄，强行渲染没有意义。
2. 纯本地存储与临时草稿恢复： 未登录状态下暂存在 localStorage / IndexedDB 中的表单数据或编辑器草稿。这些数据只存在于用户的当前浏览器中，服务端完全无感知。
3. 重度依赖 DOM 尺寸的第三方视图： 需要精确根据容器尺寸绘制像素的图表类库（如 ECharts、AntV、Canvas 游戏引擎），或集成 Monaco Editor 等重量级客户端编辑模块。跳过服务端渲染不仅避免报错，还能有效减轻服务端 Node.js 进程的 CPU 压力。
4. 用户设备强关联信息： 例如“根据用户本地系统时区显示相对时间”（如“刚刚”、“3分钟前”）。如果服务端在 UTC+0 渲染，浏览器在 UTC+8 渲染，必将引发时区展示错位。

不应跳过 SSR 的场景与反例

• 核心业务文案与 SEO 内容： 商品详情标题、价格展示、文章内容文本等。如果将其跳过服务端渲染，网络爬虫抓取的将永远是 Suspense fallback 占位符，严重损伤页面索引与搜索排名。
• 可以通过 Cookie 获知的首屏状态： 例如用户的主题模式（Dark/Light Mode）或多语言偏好（zh/en）。很多初学者习惯将主题写入 localStorage 并在客户端读取，导致必须跳过 SSR 或引发闪白。更好的做法是将主题偏好写入 HttpOnly/Cookie，让服务端在生成 HTML 时直接感知并输出正确的 CSS class，无需使用 use(browser) 降级。

六、生产环境注意事项

七、总结

React 19.3 的 use(browser) 结束了过去依靠 typeof window 和 useEffect(hasMounted) 规避水合报错的混乱历史。它让“跳过服务端渲染”成为一种由 React 核心调度器监管、与 Suspense 完美协同的一等公民机制。

在架构决策时，应当优先将 SEO 内容与关键布局保留在服务端；当遇到必须依赖硬件接口、本地离线存储或重量级客户端视图时，使用 use(browser()) 配合精准的 Suspense fallback，即可用最少、最清晰的代码，构建出无警告、零抖动的现代化全栈体验。