browser() 是什么
在 SSR 的应用里,组件会在两个环境里渲染:服务端生成初始 HTML,客户端 hydrate。大多数组件两边的输出应该一致,但有些组件在服务端生成不出有意义的 UI,比如依赖 localStorage,或者要读浏览器本地时区。
browser() 就是给这种情况提供的官方写法:
import { use } from 'react';
import { browser } from 'react-dom';
function TimeZone() {
use(browser());
const tz = new Intl.DateTimeFormat().resolvedOptions().timeZone;
return <p>{tz}</p>;
}
<Suspense fallback="Loading...">
<TimeZone />
</Suspense>工作机制
- 服务端:
use(browser())会让组件挂起(suspend),所以最近的<Suspense>的 fallback 会写进 HTML。 - 客户端:hydrate 之后它不会再挂起,组件正常渲染。
我之前说的"不会报可恢复错误"是从 changelog 里转述的,说得不够准确。更准确地说,这个组件在服务端被当成"还没准备好",用 Suspense 的 fallback 来占位,而不是靠 useEffect 或 typeof window 这类绕法。
取代了什么
以前常见两种写法:
// 写法 1:mounted 状态
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
// 写法 2:判断 window
const isBrowser = typeof window !== 'undefined';写法 2 容易造成 hydration mismatch(服务端和客户端输出不一致)。写法 1 能避免 mismatch,但要多一次渲染,而且加载态得自己处理。browser() 把加载态交给 Suspense,能和其他会挂起的组件统一协调。
可以条件调用
use 可以放在条件语句或 early return 之后,所以你可以写出"按条件决定是否跳过 SSR"的组件:
function TimeZone({ defaultValue }) {
if (defaultValue) return <p>{defaultValue}</p>; // 有默认值:服务端直接渲染
use(browser()); // 没有默认值:服务端挂起,交给浏览器
const tz = new Intl.DateTimeFormat().resolvedOptions().timeZone;
return <p>{tz}</p>;
}只有没传 defaultValue 时才会挂起。
实用场景:数据请求 Hook
官方举了一个把 useQuery 这类 Hook 包一层的例子:有 initialData(比如来自 Server Component 或框架 loader)就正常 SSR,没有就留给浏览器去请求或读缓存:
function useBrowserQuery(query, options) {
if (options.initialData === undefined) {
use(browser());
}
return useQuery(query, options);
}配套的服务端选项
react-dom/server 的 API 新增了 onBrowserBailout 选项,可以观察哪些子树因为 browser() 被推迟到了浏览器。这个选项是 changelog 里提到的,官方博客正文没有展开,具体用法需要看 react.dev 上的 browser 文档。
使用建议
- 必须包在
<Suspense>里,否则 fallback 会冒泡到更外层的边界,可能把大片内容替换成加载态。 - 这些内容在服务端不会出现在 HTML 里,SEO 和首屏内容都拿不到,只适合真正依赖浏览器环境的小范围组件。
- fallback 最好和最终内容尺寸接近,减少布局抖动。
官方文档在 react.dev/reference/react-dom/browser。
如果你想看它和 Next.js 或 Remix 这类框架怎么配合,或者要不要把现有的 mounted 写法迁移过来,我可以接着聊。