React中class和className无法作用于自定义组件的原因有哪些

和Vue、Angular默认自动将传入的class/样式类绑定到组件根节点的逻辑不同，React没有内置的组件属性自动透传机制，所有传给自定义组件的属性（包括className）都需要组件开发者显式接收、手动绑定到真实DOM节点才会生效，不存在框架层面的自动挂载逻辑，这是跨框架开发者感受到行为差异的核心原因。

以下是具体的失效场景：

• 场景1：自定义组件未接收、未绑定className prop（占90%以上的自定义组件失效问题）
  组件内部没有声明接收className参数时，外部传入的className会被直接丢弃，完全不会生效：

  // 错误写法：未接收className，外部传值直接被忽略
  function UserCard({ username }) {
    return <div className="card-base">
      <p>{username}</p>
    </div>
  }
  
  // 调用时传入的className完全不会生效
  <UserCard className="card-highlight" username="test" />
  

  修复方式非常直接：组件显式接收className，和内部基础类名拼接后绑定到目标DOM即可，多类名拼接可以用模板字符串，也可以用clsx这类轻量工具处理：

  import clsx from 'clsx'
  function UserCard({ username, className }) {
    return <div className={clsx('card-base', className)}>
      <p>{username}</p>
    </div>
  }
  

• 场景2：JSX语法使用错误
  React 18及更早版本中，原生真实DOM元素（即直接映射HTML标签的<div>、<button>等元素）只识别className属性，直接写HTML原生的class属性会被React忽略，同时控制台会抛出语法警告。
  注意：React 19虽然新增了原生DOM元素支持class属性的能力，但自定义组件不会自动处理传入的class值——写<MyComp class="test" />本质是给组件传了一个名为class的prop，组件内部如果按className字段接收，依然拿不到对应值，会导致失效。

• 场景3：第三方组件的类名接收规则不符合预期
  很多第三方组件库不会默认把className绑定到根节点：部分组件会把传入的className绑定到内部某层嵌套DOM上，部分组件（比如旧版MUI、复杂业务封装组件）要求通过classNames/classes这类专属prop传入自定义类名，还有部分封装质量差的组件根本没做className接收逻辑，外部传值不会产生任何效果。这种情况优先查对应组件的文档，确认类名的传参规则，不要想当然传className。

• 场景4：样式优先级问题被误判为className失效
  很多时候className已经成功绑定到DOM上了，但对应CSS样式的选择器权重不够，被CSS Modules、CSS-in-JS、组件库默认样式、行内样式等高优先级规则覆盖。打开浏览器开发者工具查看对应DOM元素，能看到class已经挂载，只是对应的样式规则被划掉，这种情况调整CSS选择器权重即可，不需要额外包裹div。

• 场景5：根节点为不支持属性的特殊节点
  如果组件的根节点是React.Fragment（即空标签<>...</>）、Portal、纯文本节点这类不支持属性挂载的节点，就算传了className也没有真实DOM可以绑定，自然不会生效。这种情况需要把className绑定到组件内部的真实DOM节点上，不要尝试给Fragment传任何属性。

• 场景6：SSR水合不匹配导致属性丢失
  服务端渲染场景下，如果服务端输出的DOM结构和客户端首次渲染的结构不一致，水合过程会出现属性绑定错误，可能导致className丢失，这种情况控制台会明确抛出hydration mismatch的警告，对齐两端渲染逻辑即可修复。

靠额外套一层div传className的写法会产生大量无意义的冗余嵌套节点，不属于最佳实践。正确的处理方式是给所有自定义组件预留className透传逻辑，对于不支持className透传的第三方组件，可以优先通过CSS后代选择器、:has()选择器定位目标元素修改样式，尽量减少无效DOM层级。

内容的提问来源于stack exchange，提问作者Ian Steffy