7.如何解决 SSR 场景下的 ID 冲突和可访问性问题的（useId)？ 副本
来源：https://my.feishu.cn/docx/UJ6sde6NjohBhwxc9WrcTL4fnqc
采集状态：已完成正文采集；已滚动到底部并按块及代码行号采集

SSR 场景下的 ID 难题：如何用 useId 优雅化解？​

​

在日常的前端开发中，为 DOM 元素生成唯一的 ID 是一个常见的需求，尤其是在处理表单控件、标签关联以及实现无障碍（a11y）功能时。在纯客户端渲染（CSR）的应用中，这个问题相对直接，我们可以用一个简单的计数器或者随机字符串库来解决。​

​

然而，一旦引入了服务端渲染（SSR），情况就变得复杂起来。一个经典的问题是：**服务端和客户端生成的内容必须完全一致**，否则就会导致 React 的 Hydration（注水）失败。如果我们在两端都尝试独立生成 ID，几乎不可避免地会产生不匹配，从而引发难以追踪的 bug 和糟糕的用户体验。​

​

这篇文章将探讨这个问题背后的成因，并介绍 React 18 提供的官方解决方案：useId。​

​

问题的根源：Hydration Mismatch​

​

我们常常遇到这样一个场景：创建一个需要将 label 与 input 关联的表单组件。这依赖于 label 的 htmlFor 属性和 input 的 id 属性拥有相同的值。​

​

如果在组件内部这样写：​

​

// 一个错误示范
function MyInput() {
  const id = Math.random(); // 每次渲染都生成一个随机 ID
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}

​

在 SSR 环境下，上述代码会带来严重问题。服务端在渲染时会生成一个随机 ID（例如 0.123），并将其写入 HTML。随后，当代码在客户端执行时，Math.random() 会再次运行，生成一个全新的随机 ID（例如 0.456）。​

​

当 React 尝试在客户端进行 Hydration，它会发现服务端渲染的 HTML (id="0.123") 与客户端渲染的 VDOM (id="0.456") 不匹配。这会导致 React 发出警告，并可能放弃高效的 Hydration 过程，转而进行成本更高的全量重新渲染。​

​

更重要的是，这种不匹配破坏了组件的可访问性。依赖稳定 ID 的 ARIA 属性（如 aria-labelledby）会失效，屏幕阅读器将无法正确地将标签与输入框关联起来。​

​

传统的解决方案及其局限性​

​

在 useId 出现之前，我们通常会采取一些变通方案，但它们各有不足：​

​

1.

手动传递 id**：将 id 作为一个 prop 从父组件传入。这虽然能保证 ID 的一致性，但却将确保 ID 唯一性的责任转移给了开发者。在复杂的应用中，手动管理和追踪所有 ID 会成为一个沉重的负担，组件的封装性和复用性也因此降低。

2.

使用第三方库：一些库尝试通过上下文（Context）或全局计数器来解决这个问题。虽然在某些情况下有效，但它们可能会引入额外的包体积，并且在一些高级场景下（如流式渲染、组件懒加载）同样会遇到挑战。

这些方法都像是“补丁”，而非一个根本性的解决方案。​

​

优雅的答案：useId​

​

为了彻底解决这个问题，React 18 正式引入了 useId Hook。它的设计目标十分明确：**在服务端和客户端生成稳定且唯一的 ID，同时保证两者完全一致**。​

​

useId 的使用非常直观：​

​

import { useId } from 'react';

function FormField() {
  const id = useId(); // 生成一个稳定的 ID
  
  return (
    <div>
      <label htmlFor={id}>你的名字：</label>
      <input id={id} type="text" name="name" />
    </div>
  );
}

​

在组件中调用 useId，它会返回一个唯一的、不透明的字符串（例如 :r0:）。这个字符串在服务端渲染和客户端 Hydration 期间是完全相同的。​

​

这背后的机制其实很直观。useId 生成的 ID 是基于组件在组件树中的路径推导出来的。因为组件树的结构在服务端首次渲染和客户端首次渲染时是相同的，所以通过相同路径推导出的 ID 自然也是一致的，从而完美避免了 Hydration Mismatch 问题。​

​

一个组件需要多个 ID 怎么办？​

​

在某些更复杂的组件中，我们可能需要不止一个唯一的 ID。例如，一个表单项除了输入框本身，可能还有一个关联的错误提示信息。​

​

useId 对此也提供了清晰的最佳实践：**在一个组件中，我们应该只调用一次 useId，并将其作为后续 ID 的前缀**。​

​

import { useId } from 'react';

function AdvancedField() {
  const baseId = useId();
  const inputId = `${baseId}-input`;
  const descriptionId = `${baseId}-description`;

  return (
    <div>
      <label htmlFor={inputId}>密码</label>
      <input
        id={inputId}
        type="password"
        aria-describedby={descriptionId} // 关联到描述信息
      />
      <p id={descriptionId}>
        密码应至少包含 8 个字符。
      </p>
    </div>
  );
}

​

这种模式既保证了所有 ID 的唯一性，又在语义上将它们关联了起来，代码也更加清晰。​

​

需要注意的关键点​

​

虽然 useId 功能强大，但有一个非常重要的使用场景需要我们特别注意：**不要使用 useId 生成列表中的 key**。​

​

React 的 key prop 用于在数据列表发生变化时识别哪些项被添加、移动或删除。key 必须与你的数据绑定，并且在多次渲染之间保持稳定。而 useId 生成的 ID 是基于组件的渲染路径，与数据本身无关。在列表中使用 useId 作为 key 会导致不必要的重复渲染，并可能引发与 key 设计初衷相悖的意外行为。​

​

// 错误用法：不要用 useId 作为 key
items.map(item => {
  const id = useId();
  return <li key={id}>{item.text}</li>;
});

// 正确用法：使用数据中稳定的 ID
items.map(item => (
  <li key={item.id}>{item.text}</li>
));

​

总结​

​

综上，我们可以得出一个清晰的结论：useId 是解决 React SSR 场景下 ID 唯一性和一致性问题的标准答案。它不仅解决了棘手的 Hydration Mismatch 问题，还有力地保障了应用的可访问性。​

​

后续如果遇到类似问题，可以参考这种方式：​

​

1.
识别场景：当组件需要在 label、input 或 ARIA 属性中用到唯一 ID 时。​

2.
使用 useId**：在函数组件的顶层调用 useId() 获取一个基础 ID。​

3.
派生 ID：如果需要多个 ID，使用获取到的基础 ID 作为前缀来创建它们。​

4.

避开误区：切记不要将 useId 的生成值用于列表渲染的 key。

通过拥抱 useId 这样的现代化 API，我们可以写出更健壮、更易于维护的同构应用，从容地应对现代 Web 开发中的各种挑战。​

​

本文暂未被其它文档引用