配置指南

Class2CSS 通过 class2css.config.js 文件进行配置。配置文件支持新旧两种格式，完全向后兼容。

阅读方式

如果你想“避免重复配置”，直接复制：配置模板（可复制）。
如果你刚开始用，建议先看快速开始跑通一次；再回到本页把配置补全（单位策略/排序/多文件/增量）。

配置文件位置

默认配置文件路径：./class2css.config.js

可以通过 CLI 参数 -c, --config 指定自定义路径。

最小配置（推荐做法）

当前版本建议直接从示例配置改起（更完整、并且与运行时校验一致）：

小程序（wxss / rpx）：examples/weapp/class2css.config.js + examples/weapp/styles.config.js
Web（css / px）：examples/web/class2css.config.js + examples/web/styles.config.js

你可以先用 -c 跑起来，再逐步改 multiFile.entry.path / multiFile.output。

配置结构

新版配置结构（推荐）

新版本引入了 system 配置节，提供更强大的功能：

javascript

// 推荐把“规则”拆到 styles.config.js，然后在主配置里引入，便于复用/维护
const stylesConfig = require('./styles.config.js');

module.exports = {
  system: {
    cssFormat: 'compressed',
    baseUnit: 'rpx',
    unitConversion: 2,
    compression: true,
    sortClasses: true,
    unitStrategy: {
      autoDetect: true,
      propertyUnits: {
        'font-size': 'rpx',
        'width|height': 'rpx',
        opacity: '',
        'z-index': '',
        'line-height': '',
        'border-radius': 'rpx',
      },
    },
  },

  // 单文件输出（非 multiFile 时使用；当前版本运行时通常会走 multiFile）
  output: { path: './dist', fileName: 'styles.wxss' },

  importantFlags: stylesConfig.importantFlags,

  // 多文件扫描/监听入口 + 输出策略（当前版本推荐）
  multiFile: {
    entry: { path: './src', fileType: ['wxml', 'html'] },
    output: { cssOutType: 'uniFile', path: './dist', fileName: 'styles.wxss', fileType: 'wxss' },
  },

  // 规则（来自 styles.config.js）
  atomicRules: stylesConfig.atomicRules,
  baseClassName: stylesConfig.baseClassName,
  variants: stylesConfig.variants,
  breakpoints: stylesConfig.breakpoints,
};

兼容与迁移

历史版本里常见的是 cssName / baseClassName 的配置方式；当前版本推荐以 atomicRules / baseClassName 为主，并把规则拆到 styles.config.js 便于维护。

如果你是从旧配置升级，建议直接对照示例配置做迁移（或参考仓库根目录的 MIGRATION.md）。

配置项说明

system 配置

cssFormat

CSS 输出格式，可选值：

'multiLine'：多行格式（每个规则占一行）
'singleLine'：单行格式
'compressed'：压缩格式（默认）

baseUnit

基础单位设置，默认 'rpx'。

unitConversion

单位转换比例，默认 2。
生成样式单位 = 设置单位 × 比例

例如：unitConversion: 2 时，m-10 会生成 margin: 20rpx;

compression

是否压缩CSS，默认 true。

sortClasses

是否对生成的CSS类进行字母排序（按选择器名称），默认 false。

unitStrategy

智能单位处理策略：

javascript

unitStrategy: {
  // 自动检测：如果用户写了单位，保持原单位；如果没写，使用默认单位
  autoDetect: true,
  // 属性默认单位映射
  propertyUnits: {
    'font-size': 'rpx',
    'width|height': 'rpx',
    'opacity': '',
    'z-index': '',
    'line-height': '',
    'border-radius': 'rpx'
  }
}

也可以先阅读概念页：单位与转换策略。

variants 配置（响应式 + states 伪类）

variants 用来声明可用的变体前缀（Tailwind 风格），当前支持：

responsive：sm: / md: / lg: / xl: / 2xl:（通过 @media(min-width:...) 包裹）
states：hover: / focus: / active: / disabled: / first: / last: / odd: / even:（通过伪类选择器实现）

示例（Web/小程序模板语法均可）：

html

<!-- hover 伪类 -->
<div class="hover:w-20 hover:bg-red"></div>

<!-- focus 伪类 -->
<input class="focus:w-30" />

<!-- active 伪类 -->
<button class="active:opacity-50"></button>

<!-- 组合：响应式 + hover -->
<div class="lg:hover:w-20"></div>

生成选择器示例（以 hover:w-20 为例）：

css

.hover\:w-20:hover { width: 20px; }

states 映射规则：

hover → :hover
focus → :focus
active → :active
disabled → :disabled
first → :first-child
last → :last-child
odd → :nth-child(odd)
even → :nth-child(even)

output 配置

path

输出文件目录路径。

fileName

输出文件名（包含扩展名）。

commonCssPath（可选）

公共基础样式文件路径（如果你希望每次输出都带上一段统一的基础 CSS）。

atomicRules 配置（动态规则）

推荐使用 atomicRules 描述“动态类 → CSS 属性”的规则（当前版本运行时会从 atomicRules 构建内部映射）。

javascript

atomicRules: {
  spacing: {
    m: { properties: ["margin"], defaultUnit: "rpx" },
    mt: { properties: ["margin-top"], defaultUnit: "rpx" }
  },
  sizing: {
    w: { properties: ["width"], defaultUnit: "rpx" },
    h: { properties: ["height"], defaultUnit: "rpx" }
  }
}

baseClassName 配置

静态类配置，定义预定义的CSS类：

javascript

baseClassName: {
  "container": "max-width: 1200rpx; margin: 0 auto;",
  "flex": "display: flex;",
  "flex-center": "display: flex; justify-content: center; align-items: center;"
}

颜色族配置

对于颜色相关的类，可以使用 ABBR 属性定义颜色族，然后通过颜色映射或直接颜色值来使用：

javascript

baseClassName: {
  // 颜色族：使用 ABBR 定义 CSS 属性名
  color: { ABBR: "color" },
  bg: { ABBR: "background-color" },
  bcolor: { ABBR: "border-color" },
  
  // 其他静态类...
  flex: "display: flex;"
}

// 颜色映射（通常在 styles.config.js 中定义）
const baseColor = {
  white: "#ffffff",
  black: "#000000",
  red: "#ef4444",
  // ... 更多颜色
};

// 动态合并颜色映射到颜色族
Object.values(baseClassName).forEach((item) => {
  if (item && item.ABBR) {
    Object.assign(item, baseColor);
  }
});

使用方式：

颜色映射：bg-red、color-white（需要预先配置）
直接颜色值：bg-hex-fff、color-rgb-255-0-0、bg-rgba-0-0-0-05（无需配置）

直接颜色值写法

现在支持直接在 class 中写入颜色值，无需预先配置颜色映射。详见规则参考 - 颜色。

也可以阅读概念页：Important 与静态类。

multiFile 配置（多文件模式）

用于多文件构建和增量模式：

javascript

multiFile: {
  entry: {
    path: "./src",
    fileType: ["wxml", "html"],
  },
  output: {
    cssOutType: "uniFile",
    path: "./dist",
    fileName: "styles.wxss",
    
    // 增量模式配置
    incrementalOnlyAdd: true,
    incrementalBaseline: "fromOutputFile",
    rebuildOnStart: true,
    unusedReportLimit: 200,
    
    // 统一文件写入策略
    uniFileWriteMode: "appendDelta",
  },
}

详细说明请参考增量模式。

importantFlags 配置

Important标识配置：

javascript

importantFlags: {
  suffix: ['-i', '_i'], // 后缀标识: w-100_i, w-100-i
}

配置模块化

将大型配置拆分为多个模块：

javascript

// configs/spacing.config.js
module.exports = {
  margin: {
    "m": { classArr: ["margin"], unit: "rpx" },
    "mt": { classArr: ["margin-top"], unit: "rpx" }
  }
};

// class2css.config.js
const stylesConfig = require('./styles.config.js');
const spacingRules = require('./configs/spacing.config');

module.exports = {
  system: { /* ... */ },
  atomicRules: {
    ...stylesConfig.atomicRules,
    // 把你拆出来的规则合并进去（按类别合并）
    ...spacingRules,
  },
  baseClassName: stylesConfig.baseClassName,
};

配置验证

使用内置诊断工具检查配置健康状况：

javascript

const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');

const diagnostics = new ConfigDiagnostics(eventBus, configManager);
const results = await diagnostics.runFullDiagnostics();
console.log(diagnostics.generateReport());

下一步

想直接拿一份“全功能可复制配置”：阅读配置模板（可复制）
想查当前已内置的类名规则：阅读规则参考
想先理解类名解析：阅读类名语法与生成规则
想把单位处理写稳：阅读单位与转换策略

配置指南 ​

配置文件位置 ​

最小配置（推荐做法） ​

配置结构 ​

新版配置结构（推荐） ​

兼容与迁移 ​

配置项说明 ​

system 配置 ​

cssFormat ​

baseUnit ​

unitConversion ​

compression ​

sortClasses ​

unitStrategy ​

variants 配置（响应式 + states 伪类） ​

output 配置 ​

path ​

fileName ​

commonCssPath（可选） ​

atomicRules 配置（动态规则） ​

baseClassName 配置 ​

颜色族配置 ​

multiFile 配置（多文件模式） ​

importantFlags 配置 ​

配置模块化 ​

配置验证 ​

下一步 ​

配置指南

配置文件位置

最小配置（推荐做法）

配置结构

新版配置结构（推荐）

兼容与迁移

配置项说明

system 配置

cssFormat

baseUnit

unitConversion

compression

sortClasses

unitStrategy

variants 配置（响应式 + states 伪类）

output 配置

path

fileName

commonCssPath（可选）

atomicRules 配置（动态规则）

baseClassName 配置

颜色族配置

multiFile 配置（多文件模式）

importantFlags 配置

配置模块化

配置验证

下一步