实战:Ant Design 5 在 qiankun 下的类名前缀重命名隔离

3 阅读3分钟

业务背景

接着上一篇的现状:平台里大量多年运行的存量系统,jQuery / Vue / React 混杂,需要使用最小的改动完成本次系统之间的集成。

Ant Design 默认输出 ant-* 全局类名。qiankun 环境里多个子应用共用 document,几套 antd 的样式就开始互相污染。

antd 5 提供了 ConfigProvider 的 prefixCls,可以改组件运行时输出到 DOM 的类名。但只配这个参数是不够的:因为项目里还引了设计系统主题包,主题包 CSS 和部分 ProComponents 内部的硬编码字符串依然写死 .ant-*,这部分 prefixCls 管不到。

最终方案是两条腿走路:ConfigProvider 改运行时类名 + 构建期 loader 改写静态资源。

系列文章

实现思路

  1. 运行时:全局 ConfigProvider 设置 prefixCls="sub-a",组件 DOM 输出变成 sub-a-btn、sub-a-modal;
  2. 构建期:自定义 loader 挂在 CSS 解析链前面,把静态 CSS、JS/TS 字符串里的 .ant-*、'ant-xxx' 全部替换成新前缀。

loader 只是正则文本替换,不分注释边界,注释里命中规则的字符串也会被替换;运行时拼接的类名依旧处理不了。

如果项目已经很成熟,那么就直接使用自定义loader,在构建的时候,进行整体的替换,这样对代码的改动点很小。

实现步骤

1. 全局配置 ConfigProvider

在应用根组件挂一次即可,控制组件运行时输出的类名前缀。

import { ConfigProvider } from 'antd';
import zhCN from 'antd/locale/zh_CN';

function App() {
  return (
    <ConfigProvider locale={zhCN} prefixCls="sub-a">
      {/* 业务应用入口 */}
    </ConfigProvider>
  );
}

如果项目没引第三方主题包,也没有大量手写的 .ant-* 覆盖样式,到这一步就够了,后面的 loader 不用配。

2. 编写自定义 loader

新建 loaders/replace-ant-prefix-loader.js:

// loaders/replace-ant-prefix-loader.js
const FROM = 'ant';
const TO = 'sub-a';

module.exports = function replaceAntPrefixLoader(source) {
  // CSS 选择器:.ant-btn -> .sub-a-btn
  let result = source.replace(
    new RegExp(`\\.${FROM}-([a-zA-Z0-9_-]+)`, 'g'),
    `.${TO}-$1`,
  );

  // JS 字面量字符串:'ant-tabs' -> 'sub-a-tabs',"ant-select" -> "sub-a-select"
  result = result.replace(
    new RegExp(`(['"])${FROM}-([a-zA-Z0-9_-]+)\\1`, 'g'),
    (_match, quote, name) => `${quote}${TO}-${name}${quote}`,
  );

  return result;
};

3. 注册 loader

rsbuild.config.ts 里追加一条规则。注意 import path,enforce: 'pre' 必须加,保证在 CSS 解析之前执行。

import path from 'path';

// 在 tools.rspack 里追加
config.module.rules.push({
  test: /\.(js|jsx|ts|tsx|css|less)$/,
  include: [
    path.resolve(__dirname, 'src'),
    // 会输出 .ant-* 的业务设计系统包,必须一起处理
    /node_modules[\\/]@your-ds/,
  ],
  enforce: 'pre',
  use: [
    {
      loader: path.resolve(__dirname, 'loaders/replace-ant-prefix-loader.js'),
    },
  ],
});

三个参数各自的意义:

  • enforce: 'pre':必须早于 CSS 解析链,否则选择器已经进 AST,字符串替换改不动;
  • test 带 js|jsx|ts|tsx:组件包把类名写在 JS 字符串里,只处理 CSS 是不够的;
  • include 覆盖全部来源:漏一个包,等于没做。

4. 业务样式怎么写

loader 会自动改写源码里的 .ant-*,所以业务代码继续按 antd 官方类名写就行,构建后自动换成新前缀:

export default createStyles(({ css }) => ({
  modal: css`
    .ant-modal-content {
      border-radius: 4px;
    }
  `,
}));

构建产物里会变成 .sub-a-modal-content。也可以直接写 .sub-a-*,loader 不会重复处理。建议团队统一一种写法,别在同一个文件里两种前缀混着来。

生产环境踩坑记录

坑 1:只配 prefixCls,没配 loader

现象:组件本体样式正常,主题色、圆角、间距全不对。

原因:prefixCls 只改运行时 DOM,改不到第三方包里写死的静态 CSS。DOM 上已经是 .sub-a-btn,主题包里的 .ant-btn { ... } 自然匹配不上。

坑 2:include 漏了设计系统包

现象:页面看着「没套主题」。

原因:include 只写了 src,node_modules 下主题包的 CSS 没进 loader。

坑 3:ProComponents 部分组件样式失效

有些类名写在 JS 字符串字面量里,如果 loader 只处理 css 文件,JS 根本不会被改写。

所以 test 一定要带上 js / ts / tsx。

坑 4:rc-* 底层包不用处理

rc-select、rc-picker 里的 ant- 大多是注释里的 issue 链接,真实类名是 antd 通过 prefixCls 参数传进去的,不需要纳入 include。

验证一下:

grep -rn "ant-" node_modules/rc-select/es/*.js | grep -v "github.com"

坑 5:anticon 图标类名不会被替换

正则匹配的是 .ant-,anticon 没有连字符,命中不了。这是有意保留的:图标类名冲突概率低,antd 内部还依赖它注入图标样式。强行替换要同步改图标注入逻辑,风险大于收益。

坑 6:正则版 loader 的两个短板

  • 注释会被误伤:/* .ant-btn 示例 */ 里的文本也会被替换,不影响运行但会干扰 grep 排查;
  • 动态拼接抓不到:const cls = 'ant-' + size 这种运行时拼接,任何静态 loader 都无能为力,只能靠 prefixCls 统一入口。

真要求「只改选择器」,CSS 部分换成 PostCSS 解析:

const postcss = require('postcss');

module.exports = function (source) {
  const root = postcss.parse(source);
  root.walkRules((rule) => {
    rule.selector = rule.selector.replace(/\.ant-/g, '.sub-a-');
  });
  return root.toString();
};

代价是多一个依赖,含 Less 语法(变量、嵌套)的文件还得传 postcss-less 当 parser;JS 侧继续用字符串正则。CSS 走 PostCSS、JS 走正则,性价比最高。

构建产物校验

构建完跑一个脚本,把「有没有残留」变成可量化的数字,别靠肉眼。

保存为 check-ant-prefix.js,在项目根目录执行 node check-ant-prefix.js。

const fs = require('fs');
const path = require('path');

const DIST = 'dist';

function walk(dir) {
  return fs.readdirSync(dir).flatMap((name) => {
    const full = path.join(dir, name);
    return fs.statSync(full).isDirectory() ? walk(full) : [full];
  });
}

let residual = 0;
let renamed = 0;

for (const file of walk(DIST)) {
  if (!/\.(css|js)$/.test(file)) continue;
  const raw = fs.readFileSync(file, 'utf8');
  // 去掉注释和 URL,避免把 issue 链接算成残留
  const cleaned = raw.replace(/\/\*[\s\S]*?\*\/|github\.com\S*/g, '');
  residual += (cleaned.match(/\.ant-[a-z]/g) || []).length;
  renamed += (cleaned.match(/\.sub-a-[a-z]/g) || []).length;
}

console.log('.ant- 残留:', residual, '(必须为 0)');
console.log('.sub-a- 命中:', renamed, '(必须大于 0)');

浏览器侧再确认一遍类名:

  • Button → sub-a-btn
  • Modal → sub-a-modal
  • Table → sub-a-table
  • DatePicker → sub-a-picker
  • 图标 → anticon(保持不变)
  • 多子应用同时运行,互不影响

业务开发注意事项

  1. 写覆盖样式继续写官方 .ant-*,交给 loader 处理,别一半手写一半自动;
  2. 新增第三方包,先确认它是否输出 .ant-*,再决定要不要加进 include;
  3. 升级 antd 或主题包,重跑校验脚本,重点看残留是不是 0;
  4. loader 只管构建期静态源码,JS 动态拼类名的场景要业务自己兜。