Rolldown项目中Hook Filter与CreateFilter的行为差异分析

在Rolldown项目的开发过程中，我们发现了一个关于模块过滤机制的有趣现象：通过Hook Filter直接指定的过滤条件与使用createFilter工具函数创建的过滤器，在处理相同模块ID时表现出不同的行为模式。

问题背景

在构建工具中，模块过滤是一个常见需求。Rolldown和Vite都提供了两种方式来定义模块过滤规则：

1. 直接在Hook中通过filter属性指定
2. 使用createFilter工具函数创建过滤器

这两种方式看似应该产生相同的结果，但实际上它们对相同输入的匹配行为存在差异。

行为差异的具体表现

通过实际测试发现，当处理"virtual:foo"这样的虚拟模块ID时：

• 直接使用Hook Filter的filter: { id: "virtual:foo" }能够正确匹配"virtual:foo"
• 而使用createFilter("virtual:foo")创建的过滤器却无法匹配相同的ID

这种差异在WASI运行时环境下表现得尤为明显，可能导致构建行为不一致的问题。

技术原理分析

深入研究发现，这种差异源于createFilter内部实现中对路径的特殊处理。Rollup的createFilter实现会考虑当前工作目录(cwd)因素，对输入路径进行规范化处理：

1. 它会尝试将路径转换为相对于cwd的相对路径
2. 这种转换过程可能导致某些特殊路径(如虚拟模块路径)的匹配失败

而Hook Filter的实现则更为直接，它采用简单的字符串匹配机制，不涉及任何路径转换逻辑，因此能够正确匹配原始ID。

解决方案讨论

项目维护者提出了几种可能的解决方案：

1. 完全移除路径规范化处理逻辑，使两种过滤方式行为一致
2. 保留差异但明确文档说明
3. 修改WASI环境下的特殊处理

经过讨论，倾向于采用第一种方案，即简化过滤逻辑，移除不必要的路径转换处理。这种方案有以下优势：

• 保持API行为直观可预测
• 避免因环境差异导致的构建不一致
• 简化实现复杂度
• 解决WASI环境下的特殊问题

对开发者的建议

对于使用Rolldown或Vite的开发者，在处理模块过滤时应注意：

1. 如果使用虚拟模块，推荐直接使用Hook Filter语法
2. 需要跨环境一致性时，避免依赖createFilter的路径处理行为
3. 在插件开发中保持过滤逻辑简单直接

这种设计决策体现了构建工具开发中的一个重要原则：在功能强大性和行为可预测性之间取得平衡，优先保证核心场景的稳定性和一致性。