LightningCSS 中组合多个自定义规则转换器的问题解析

问题背景

在使用 LightningCSS 进行 CSS 处理时，开发者经常需要处理自定义的 @规则（如 @light 和 @dark），并将它们转换为标准的 CSS 媒体查询。然而，当尝试使用 composeVisitors 方法组合多个规则转换器时，发现只有最后一个规则会被正确应用。

问题现象

开发者尝试同时转换 @light 和 @dark 两个自定义规则为对应的媒体查询，但输出结果显示只有其中一个规则被正确处理。具体表现为：

• 单独使用 @light 规则转换器时，能正确转换为 @media (prefers-color-scheme: light)
• 单独使用 @dark 规则转换器时，能正确转换为 @media (prefers-color-scheme: dark)
• 同时组合使用时，只有其中一个转换生效

技术分析

composeVisitors 的限制

LightningCSS 提供的 composeVisitors 方法在组合多个规则转换器时存在以下限制：

1. 覆盖行为：当多个转换器对同一规则进行定义时，后面的转换器会覆盖前面的，而不是合并
2. 部分节点类型丢失：某些特定的节点类型（如 StyleSheet 和 StyleSheetExit）的处理函数会被丢弃
3. 缺乏深度合并：对于嵌套结构的规则定义，无法进行深度合并

临时解决方案

开发者提出了两种临时解决方案：

1. 使用 lodash 的 merge 方法：

   function composePlugins(plugins) {
     let customAtRules = {};
     let visitor = {};
     plugins.forEach(p => {
       if ('visitor' in p) {
         _.merge(visitor, p.visitor);
         if (p.customAtRules) Object.assign(customAtRules, p.customAtRules);
       } else {
         _.merge(visitor, p);
       }
     });
     return { customAtRules, visitor };
   }
   

2. 手动合并特定规则：

   const mergedVisitor = {
     Rule: {
       custom: {
         light: firstVisitor.Rule.custom.light,
         dark: secondVisitor.Rule.custom.dark
       }
     }
   };
   

深入理解

自定义规则转换机制

LightningCSS 允许开发者通过 customAtRules 定义自定义的 @规则，并通过 visitor 模式来转换这些规则。典型的转换流程包括：

1. 定义自定义规则的结构（prelude 和 body 类型）
2. 为每种自定义规则提供转换函数
3. 将转换函数应用到 CSS 抽象语法树（AST）上

理想的组合方式

理想情况下，规则转换器的组合应该：

1. 保留所有自定义规则的处理函数
2. 支持深度合并嵌套结构
3. 不丢失任何节点类型的处理逻辑
4. 保持处理顺序的可预测性

最佳实践建议

1. 单一职责原则：每个转换器只处理一种自定义规则
2. 手动合并关键规则：对于必须组合使用的规则，显式地合并处理函数
3. 测试验证：对组合后的转换器进行充分测试，确保所有规则都被正确处理
4. 关注官方更新：留意 LightningCSS 的版本更新，可能会修复此问题

总结

LightningCSS 的 composeVisitors 方法在处理多个自定义规则转换器时存在局限性，开发者需要采用替代方案来实现规则的组合转换。理解这一限制有助于在 CSS 处理流程中做出更合理的设计决策，确保所有自定义规则都能被正确转换。随着项目的演进，这一问题有望在未来的版本中得到解决。