Ant Design 5项目中如何继续使用CSS与Less样式

Ant Design 5 支持在 Less 构建阶段完成主题定制，整体流程并不复杂：先引入 antd.variable.less，再根据项目需求覆盖对应变量，最后通过 lessc --js 编译生成一份独立的 CSS 文件。需要特别注意的是，这种主题定制方案不能与 ConfigProvider.theme 同时使用；如果项目属于 SSR 场景，则必须优先采用这种构建时编译方案。

虽然 Ant Design 5 默认启用了 CSS-in-JS 机制，但在实际开发中，你依然可以继续使用 Less 来编译主题，也可以通过纯 CSS 的方式引入样式。关键在于避开默认的运行时样式注入链路，改为使用构建阶段的编译路径，这也是很多传统项目、SSR 应用和微前端场景更常见的做法。

为什么直接 import 'antd/dist/antd.css' 后改 Less 变量无效？

antd/dist/antd.css 本质上是一份已经预编译完成的静态 CSS 文件，其中原有的 Less 变量早已被替换为具体的颜色值、尺寸值和样式结果。也正因如此，即使你在 Less 文件中重新定义 @primary-color，它也不会对这份 CSS 产生任何影响——归根结底，这个文件并不会再次参与 Less 编译流程。

• 所有自定义主题变量都必须在 antd/dist/antd.variable.less（v5）或 antd/dist/antd.less（v4 兼容模式）加载之前注入
• 不能在组件级的 Button.module.less 中覆盖全局变量，因为作用域限制会导致全局主题变量不生效
• Webpack 项目需要确保 less-loader 配置了 ja vascriptEnabled: true，否则像 color(~`@{primary-color}`) 这样的函数会直接报错

如何用 Less 编译出一套可 CDN 引入的 antd 主题 CSS？

目标是生成一个独立的 my-theme.css，不依赖 JavaScript 运行时，适合在 SSR、微前端或传统 HTML 页面中通过 标签直接引入，这也是很多项目进行 Ant Design 主题定制时常用的方式。

• 新建 src/theme.less，第一行必须写成 @import "antd/dist/antd.variable.less";（v5）或 @import "antd/dist/antd.less";（v4 兼容模式）
• 紧接着编写变量覆盖，例如：@primary-color: #13c2c2;、@border-radius-base: 4px;，不要添加 !important，也不要通过重写选择器来替代变量配置
• 使用 lessc --js src/theme.less dist/my-theme.css 执行编译，--js 参数不能省略，因为 v5 的 antd.variable.less 内部包含 JS 计算逻辑
• 如果通过 Node.js 脚本调用 Less 编译器，则需要传入选项 { ja vascriptEnabled: true }

ConfigProvider.theme 和 Less 主题能混用吗？

不能混用。两者属于完全不同的主题机制：前者依赖运行时注入 CSS Variables，后者则是在构建阶段将 class 名和样式值直接固化到最终 CSS 中。如果同时使用，通常会引发样式冲突、优先级混乱或覆盖失效等问题。

• ConfigProvider 修改的 token 会生成类似 --ant-primary-color 这样的 CSS 变量，并由 JavaScript 动态写入 :root；而 Less 编译后的结果则是类似 .ant-btn { color: #13c2c2; } 这样的固定样式代码
• 如果项目已经使用了 ConfigProvider，就不应再额外引入自行编译的 Less 主题 CSS，否则按钮、边框、背景色等样式可能会被两套规则反复覆盖
• 在 SSR 场景中，更建议优先使用 Less 编译主题方案——因为服务端无法执行 JavaScript 来注入 CSS 变量，ConfigProvider 的 theme 首屏渲染通常无法正常生效

真正容易出问题的地方，并不是写几行 Less 变量，而是主题变量的注入时机是否正确，以及整个 Less 编译链路是否完整。无论是遗漏 --js 参数、写错 @import 顺序，还是保留了 antd.css 没有移除，都可能导致 Ant Design 5 的主题定制在构建过程中静默失效，最终看起来像是“修改变量没反应”。