JSX里class为什么必须写成className？

分类：前端工程 / React 核心原理

图 0：JSX 样式类名属性与底层 JavaScript 运行时及 DOM 体系的映射总览

一、为什么必须写成 className：两大致命核心原因

初学 React 的开发者几乎都会遇到这样的困惑：在编写标准 HTML 时，为元素添加样式类使用的是 <div class="container">；但只要把同样的代码粘贴到 React 组件的 JSX 中，就必须老老实实地换成 <div className="container">。如果执意写成 class，控制台就会立刻弹出醒目的红色警告。

这并不是 React 团队为了标新立异而故意设置的语法门槛，而是由 底层的 DOM 标准接口设计 与 JavaScript 宿主语言规范 共同决定的。

1. 底层 DOM 规范：元素对象的属性名原本就是 className

很多前端开发者容易将“HTML 标签上的属性”与“浏览器内存中的 DOM 节点属性”混为一谈。在 W3C 的 HTML 规范中，标签上的特性被称为 Attribute（特性），例如文本 class="btn"；而当浏览器解析 HTML 并生成真实的 DOM 树后，每个标签对应的是一个继承自 HTMLElement 的 JavaScript 对象。

在 DOM Level 2 乃至最新的 HTML DOM 标准中，为了避免与 ECMAScript 的关键字冲突，规范制定者将 DOM 对象上对应 class 特性的属性正式命名为 className。如果你在浏览器控制台执行原生 JavaScript：

const div = document.createElement('div');
div.className = 'active-box'; // 标准的 DOM Property 赋值方式
console.log(div.className);   // 输出 "active-box"
console.log(div.class);       // 输出 undefined，DOM 对象上根本没有 class 属性！

React 的核心理念是“用纯粹的 JavaScript 来表达视图”。React 的 Virtual DOM（虚拟 DOM）在设计之初就优先映射原生 DOM 对象的属性（Properties），而不是解析后的 HTML 字符串。因此，React 选择了直接对应 node.className 的命名方式。

2. JavaScript 语言历史：class 作为保留关键字的包袱

JSX 诞生于 2013 年左右。在 JavaScript 语言的 ECMAScript 规范中，class 长期被列为保留关键字（Reserved Words），并在 ES6（ECMAScript 2015）中正式用于定义类（如 class App extends Component）。

在老旧的 JavaScript 运行环境（例如 IE8 及更早版本的 JScript 引擎）中，对象字面量使用未加引号的保留字作为属性名会直接引发致命的语法解析错误（Syntax Error）：

// 在旧版本 JS 引擎中会直接 Syntax Error: Unexpected reserved word 'class'
var props = {
  class: 'header-wrapper' // 报语法错误！必须写成 'class': 'header-wrapper'
};

即便在现代 JavaScript 中对象字面量的键名已经允许使用保留字，但在对对象进行解构赋值（Destructuring Assignment）时，class 依然无法直接作为合法变量名使用：

// 错误写法：class 无法作为解构出的本地变量名
function MyComponent({ class, id }) { // SyntaxError: Unexpected token 'class'
  return <div id={id}>内容</div>;
}

// 必须写成别名重命名，极度别扭：
function MyComponent({ class: className, id }) {
  // ...
}

如果 React 强行允许在 JSX 属性中使用 class，开发者在自定义组件、提取 props 或解构参数时就会频繁触发语法错误。为了保证属性在 JavaScript 代码中自由流转、传参与解构，选用 className 彻底消除了一切关键字冲突的隐患。

二、从 JSX 到真实 DOM：底层编译与挂载全流程

要彻底搞懂 className 的流转过程，我们需要观察一段简单的 JSX 是如何一步步变成浏览器屏幕上的真实节点的。

function Card({ title }) {
  return <div className="card-box">{title}</div>;
}

浏览器本身完全不认识 JSX 语法。构建工具（如 Babel、SWC 或 TypeScript）在打包编译阶段，会把上述 JSX 转换为标准 JavaScript 函数调用。

function Card({ title }) {
  return React.createElement('div', {
    className: 'card-box'
  }, title);
}

import { jsx as _jsx } from 'react/jsx-runtime';

function Card({ title }) {
  return _jsx('div', {
    className: 'card-box',
    children: title
  });
}

无论是旧版的 React.createElement 还是现代的 _jsx，传入的第二个参数都是一个普通的 JavaScript 对象（即 props 对象）。当 React 渲染器（React DOM）在 Reconciliation（协调阶段）后创建真实 DOM 节点并挂载属性时，底层关键逻辑大致如下：

// React 内部将虚拟属性同步到真实 DOM 节点的简化逻辑
function setInitialDOMProperties(domElement, props) {
  for (const propKey in props) {
    const nextProp = props[propKey];
    if (propKey === 'className') {
      // 直接作为 DOM 对象的属性赋值，而不是每次都调用 setAttribute
      domElement.className = nextProp ? '' + nextProp : '';
    } else if (propKey === 'style') {
      // 设置内联样式对象
      setValueForStyles(domElement, nextProp);
    } else if (propKey === 'children') {
      // 处理子节点
    } else {
      // 处理其他标准属性与自定义特性
      setGenericAttribute(domElement, propKey, nextProp);
    }
  }
}

图 1：JSX className 从代码编写到 DOM 挂载的 4 步执行流

三、关键概念厘清：HTML Attribute 与 DOM Property 的本质区别

要想彻底理解这个问题，必须深入区分 Web 开发中两个最容易被混淆的概念：Attribute（HTML 特性）与 Property（DOM 属性）。

可以看到，除了 class 必须对应 className 之外，另一个经典的例子就是表单标签的 for 属性：

// HTML 写法：
<label for="username">用户名</label>

// JSX 写法：因为 for 是 JavaScript 中循环结构的关键字，所以必须使用 DOM Property 的 htmlFor
<label htmlFor="username">用户名</label>

这两者的逻辑完全一致：React 坚守了“JSX 属性贴合 DOM Property 优先原则”，凡是与 JavaScript 语言本身发生命名冲突的属性，均统一遵循 DOM Level 2 标准给出的安全属性名替代方案。

图 2：HTML Attribute 与 DOM Property 映射体系对比图

四、如果坚持在 JSX 里写 class 会发生什么？

有些好奇的开发者可能会尝试：“如果我偏不听，硬要在 React 组件里写 <div class="box">，页面能正常显示吗？”

答案取决于你所使用的 React 版本：

1. 控制台报出显眼的警告

无论是在 React 16、17、18 还是 19 的开发环境（Development Mode）下，只要你在 JSX 中写了 class，React 就会在浏览器控制台打印如下警告：

2. 真实 DOM 的渲染表现差异

• React 16 之前：React 内部有一张严格的白名单。不在白名单中的属性（如 class）会被完全忽略，根本不会出现在最终渲染的 DOM 节点上，导致你的样式完全失效。
• React 16 及更高版本：React 引入了未知属性传递机制（Unknown Attributes Passing）。即使识别出了未标准化的 class 属性，除了抛出上述控制台警告外，React 依然会尝试将其以 HTML 特性的形式调用 setAttribute('class', value) 挂载到 DOM 上。

尽管在较新版本的 React 中即使写错也可以勉强生效，但绝对不能在生产代码中滥用这种容错机制。原因包括：

1. 服务端渲染（SSR）与水合不一致：在 Next.js 或 Remix 等 SSR 框架中，服务端渲染生成的 HTML 与客户端 Hydration 时对属性的处理可能存在细微差异，极易触发 Hydration mismatch 报错。
2. 组件库与类型检查报错：在 TypeScript 环境中，@types/react 的 HTMLAttributes<T> 接口只定义了 className?: string，写 class 会直接引发 TypeScript 编译错误：Property 'class' does not exist on type 'DetailedHTMLProps<...>'。
3. 团队代码风格断裂：静态代码检查工具（如 ESLint 的 react/no-unknown-property 规则）会直接将此类代码判定为 Error 级别报错，阻止代码合并与发布流水线。

五、横向对比：为什么 Preact、Vue JSX 和 SolidJS 可以直接写 class？

很多接触过其他前端框架的开发者会发现：同样是类似 JSX 的写法，Preact、Vue 3 JSX 或 SolidJS 却允许甚至鼓励直接书写 class。它们难道没有受到 JavaScript 保留字的困扰吗？

图 3：不同前端框架对待 class 与 className 的实现取舍对比

之所以有这样的差异，本质上是因为这些框架诞生的时代背景和设计哲学不同：

• 时代背景不同：React 制定 JSX 规范是在 2013 年，当时 ES3 兼容性仍是不可忽视的包袱；而 Vue 3、SolidJS 诞生于现代 ES6+ 时代，所有运行时天然支持对象字面量使用保留字。
• 编译阶段的介入程度不同：SolidJS 和 Vue 深度依赖专门的定制编译器，可以在编译期自动把 class="..." 转换成正确的 DOM 属性赋值操作；而 React 的 JSX 编译器定位非常轻量，它只负责单纯的“语法还原”，尽量不把业务逻辑和复杂的特殊规则塞进编译插件中。
• 保持 React 生态的向后兼容：React 拥有全球最庞大的前端生态库，任何对于核心基础属性签名的重大修改都会给成千上万的第三方 UI 库、类型声明和现有项目带来巨大的破坏性变更。因此，React 团队始终保持 className 的设计基准。

六、日常开发中的最佳实践与常见写法

在实际的 React 项目中，我们几乎每天都要处理动态类名、条件判断与多状态组合。以下是几种最常用且规范的类名书写范式：

1. 静态与单类名场景

最简单的固定样式类名，直接书写纯字符串即可：

function Button() {
  return <button className="btn btn-primary">提交</button>;
}

2. 简单条件类名：模板字符串（Template Literals）

当类名依赖组件内部的状态或 Props 时，可以使用 ES6 的模板字符串配合三元运算符：

function Alert({ type, isVisible, message }) {
  return (
    <div className={`alert-box alert-${type} ${isVisible ? 'fade-in' : 'hidden'}`}>
      {message}
    </div>
  );
}

3. 复杂工程场景：使用 clsx 或 classnames 工具库

随着条件分支增多，模板字符串容易出现多余的空格或生成 "undefined"、"false" 等非法类名字符串。现代前端工程通常采用轻量高效的类名工具库（首推超轻量级的 clsx）：

import clsx from 'clsx';

function DropdownItem({ active, disabled, isFirst, isLast }) {
  return (
    <div
      className={clsx('menu-item', {
        'is-active': active,
        'is-disabled': disabled,
        'border-t-0': isFirst,
        'border-b-0': isLast
      })}
    >
      选项
    </div>
  );
}

4. 搭配 Tailwind CSS / CSS Modules

在 Tailwind CSS 或 CSS Modules 架构下，同样遵循 className 规范。搭配 clsx 和 tailwind-merge 可以完美解决样式覆盖冲突：

import { twMerge } from 'tailwind-merge';
import clsx from 'clsx';

export function cn(...inputs) {
  return twMerge(clsx(inputs));
}

// 在组件中使用，即使传入自定义类名也能安全覆盖默认 Tailwind 样式
function CustomButton({ className, ...props }) {
  return (
    <button
      className={cn('px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700', className)}
      {...props}
    />
  );
}

七、知识结构总结与避坑清单

最后，我们将 JSX 里 class 为什么必须写成 className 的全部知识要点与避坑策略浓缩如下：

图 4：JSX className 核心原理与日常开发防错指南

• 牢记 DOM 原生属性映射：JSX 并不是字符串拼接引擎，它通过 JavaScript 对象描述视图，className 是原生 DOM 对象的标准属性名。
• 同理类推 htmlFor：遇到表单的 <label> 时，将 for 写成 htmlFor，底层原因完全一致。
• 杜绝侥幸心理：新版 React 虽然有未知属性透传机制，但控制台警告、TypeScript 报错以及潜在的水合失效代价极高，必须规范使用 className。
• 善用工具库：条件复杂的组件中，果断采用 clsx 替代冗长容易出错的手工模板字符串拼接。