@bi-plugin/plugin-unicode-fix

Rsbuild 插件：修复 SASS 编译过程中 Unicode 字符被破坏的问题，专门用于解决 ElementUI 图标在编译后显示为乱码的问题。

特性

• 🔧 自动修复 - 构建完成后自动修复 CSS 文件中的 Unicode 字符
• 🎯 智能映射 - 优先使用 bi-icons，回退到 element-icons
• 📦 多包管理器支持 - 兼容 npm、pnpm、yarn 的不同路径结构
• 🚀 零配置 - 开箱即用，无需额外配置
• 📝 详细日志 - 提供详细的修复过程日志
• 🛡️ 错误处理 - 优雅的错误处理和回退机制

安装

# npm
npm install @bi-plugin/plugin-unicode-fix

# pnpm
pnpm add @bi-plugin/plugin-unicode-fix

# yarn
yarn add @bi-plugin/plugin-unicode-fix

使用方法

基本用法

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginUnicodeFix } from '@bi-plugin/plugin-unicode-fix';

export default defineConfig({
  plugins: [
    pluginUnicodeFix(),
  ],
});

高级配置

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginUnicodeFix } from '@bi-plugin/plugin-unicode-fix';

export default defineConfig({
  plugins: [
    pluginUnicodeFix({
      // 是否启用详细日志
      verbose: true,
      
      // 自定义图标映射文件路径
      iconPaths: {
        biIcons: 'custom/path/to/bi-icons.css',
        elementIcons: 'custom/path/to/element-icons.css',
      },
      
      // 是否在构建失败时继续执行
      continueOnError: true,
    }),
  ],
});

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | verbose | boolean | true | 是否启用详细日志 | | iconPaths | object | undefined | 自定义图标映射文件路径 | | iconPaths.biIcons | string | undefined | bi-icons CSS 文件路径 | | iconPaths.elementIcons | string | undefined | element-icons CSS 文件路径 | | continueOnError | boolean | true | 是否在构建失败时继续执行 |

工作原理

1. 构建完成后触发 - 使用 onAfterBuild 钩子在构建完成后执行
2. 扫描 CSS 文件 - 自动扫描构建输出目录中的所有 CSS 文件
3. 动态读取映射 - 自动读取 node_modules/bi-eleme 中的图标定义
4. 智能修复 - 使用正则表达式匹配和替换错误的 Unicode 字符
5. 优先级策略 - 优先使用 bi-icons 的 Unicode 值，回退到 element-icons

支持的图标格式

插件支持以下 CSS 格式的图标定义：

/* 单行格式 */
.el-icon-download:before{content:"\e911"}

/* 多行格式 */
.el-icon-download:before {
  content: "\e911";
}

兼容性

• 包管理器: npm, pnpm, yarn
• 构建工具: Rsbuild 1.x
• Node.js: >= 18.12.0

常见问题

Q: 插件没有找到图标文件怎么办？

A: 插件会自动尝试多种路径来查找图标文件，如果仍然找不到，会使用默认的 Unicode 映射。你也可以通过 iconPaths 选项手动指定文件路径。

Q: 如何禁用详细日志？

A: 设置 verbose: false 即可禁用详细日志输出。

Q: 插件支持哪些包管理器？

A: 插件支持 npm、pnpm、yarn 等主流包管理器，会自动适配不同的路径结构。

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License