26.5 资源加载与文档元数据原生 API

在 React 19 之前，管理 <head> 中的元数据（如 <title>、<meta>、<link>）通常需要依赖第三方库（如 react-helmet）或手动在 useEffect 中操作 DOM。这些方案不仅繁琐，还容易出现标签重复、更新不及时、SSR 支持不完善等问题。React 19 带来了原生的文档元数据组件和资源预加载 API，让开发者可以在组件树中声明式地管理这些内容。

内置元数据组件

React 19 提供了以下可以直接在 JSX 中使用的组件：

<title>：设置页面标题。
<meta>：设置 <meta> 标签。
<link>：设置外部资源链接，如样式表、图标等。
<script>：控制脚本加载。

这些组件可以出现在组件树的任何位置，包括深层子组件和延迟加载的组件。React 会自动将它们提取并渲染到 <head> 中，同时处理去重和更新——如果两个组件渲染了相同 name 的 <meta>，后渲染的会覆盖先渲染的，避免重复标签。

基础示例

import { title, meta, link } from 'react';

function ProductPage({ product }) {
  return (
    <div>
      <title>{product.name} - 我的商城</title>
      <meta name="description" content={product.description} />
      <link rel="canonical" href={`https://example.com/products/${product.id}`} />
      {/* 页面内容 */}
    </div>
  );
}

在这个例子中，无论 ProductPage 嵌套多深，React 都会把这些标签提升到 <head>，产品名称变化时自动更新标题和描述。

自动去重与更新规则

这些组件是稳定的节点：React 只会保留最后渲染的具有相同“标识”的标签，避免出现多个相互矛盾的页面描述。

<title>：始终只有一个，最后一次渲染的生效。
<meta>：如果 name 属性相同，视为同一标签，后渲染覆盖前渲染；如果 property 相同（如 Open Graph），同理。
<link>：如果 rel 和关键属性相同，覆盖更新。

function Layout() {
  return (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="theme-color" content="#ffffff" />
    </>
  );
}

function PageA() {
  return <meta name="theme-color" content="#ff0000" />;
}

function PageB() {
  return <meta name="theme-color" content="#00ff00" />;
}

当路由切换到 PageA 时，theme-color 变为红色；切换到 PageB 时变为绿色，不会出现两个 theme-color 标签。

资源预加载 API

除了静态元数据，React 19 还提供了命令式的资源预加载方法，挂在 ReactDOM 上。这些方法可以在组件渲染之前提前发现和加载所需资源，配合 Suspense 实现无缝体验。

ReactDOM.preload(href, options)：预加载资源（字体、图片等）。浏览器会提前下载并缓存。
ReactDOM.preloadModule(href, options)：预加载 ES 模块。
ReactDOM.preconnect(href, options)：提前建立到源站的连接（DNS + TCP + TLS）。
ReactDOM.prefetchDNS(href)：仅解析 DNS。

这些方法应该在事件处理函数或 useEffect 中调用，不应在渲染期间调用。React 会智能地与 Suspense 协调：当组件开始取数据时，可以同时触发相关资源的预加载，确保数据到位时资源也已经准备好。

典型场景：动态预加载字体

import { useEffect } from 'react';
import ReactDOM from 'react-dom';

function LandingPage() {
  useEffect(() => {
    // 预加载自定义字体，确保首屏文字无闪烁
    ReactDOM.preload('/fonts/custom.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
    // 提前建立到 CDN 的连接
    ReactDOM.preconnect('https://cdn.example.com');
  }, []);

  return <h1 style={{ fontFamily: 'CustomFont' }}>欢迎</h1>;
}

与 Suspense 和流式渲染的集成

在流式 SSR (Streaming SSR) 场景中，元数据组件和预加载 API 的开箱即用优势更加明显。传统的手动 useEffect 方案在客户端渲染前 <head> 中缺少正确的标签，导致 SEO 和社交分享预览失效。React 19 的元数据组件会在服务端渲染时就提取到 <head>，并在客户端水合后继续保持同步更新。

// 这段代码在服务端也会正确生成 <title> 和 meta 标签
<App>
  <Suspense fallback={<Spinner />}>
    <ProductDetailPage />
  </Suspense>
</App>

注意事项

卸载时自动清除：当组件卸载，它所渲染的元数据也会被移除，页面会回到上一个有效状态。
与旧浏览器的兼容性：这些 API 在 React 19 中可用，需要对应的 react-dom 版本。确保构建工具配置了对应的 Node 版本和 polyfill（通常不需要额外 polyfill）。
不要滥用预加载：预加载太多资源反而会阻塞关键路径，应该只对当前页面首屏必需的字体、CSS、JS 进行预加载。

小结

React 19 的原生元数据与资源加载 API 让开发者告别了第三方 head 管理库，带来了声明式的开发体验、自动去重、与 Suspense 深度集成以及完美的 SSR 支持。在大型应用中，这些细节能显著提升页面性能和维护性，是“开箱即用”的又一进步。