Rolldown Module ID 解析：字符串路径身份的归一化设计与跨平台一致性

Rolldown Module ID 解析：字符串路径身份的归一化设计与跨平台一致性

【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown

Module ID 是 Rolldown 整个打包器的"主键"——模块图、增量缓存、插件 API、HMR、文件监听都以它为键。本文基于 Rolldown 仓库内部设计文档 internal-docs/module-id/implementation.md，系统讲解 Module ID 的字符串路径身份机制：Rollup 如何用单点归一化解决路径一致性问题、Rolldown 的ModuleId三分类设计与StableModuleId稳定化方案，以及路径身份在哪些边界上存在静默失效风险。读完本文，你将理解模块 ID 的完整生命周期、各子系统的键约定，以及路径比较中字符串相等与PathBuf组件比较的本质差异。

Module ID：整个打包器的主键

Rolldown 中，Module ID 是整个 bundler 的主键（primary key），贯穿六大子系统：

• 模块图（module graph）：以 Module ID 唯一标识每个模块节点；
• 缓存（caches）：增量构建时以 ID 为键保存扫描阶段结果；
• 插件 API：get_module_info()、resolveId、load、transform等钩子中插件所见、所传的都是模块 ID；
• HMR：客户端与服务端之间通过稳定 ID 对齐模块；
• watch 文件：文件监听事件需要匹配到模块；
• graph.watchFiles：插件通过addWatchFile()声明的监听文件集合。

在 Rolldown 中，Module ID 是基于ArcStr（原子引用计数的不可变字符串）实现的，因此路径身份（path identity）完全取决于精确的字符串相等性（exact string equality）——"/foo/bar"与"/foo/bar/"是同一个文件，却是两个不同的 Module ID。本文要回答的核心问题就是：路径如何在这些子系统之间流转、失配（mismatch）会发生在哪里，以及 Rollup 是如何解决同一问题的。

Rollup 的做法：单点归一化设计

Rollup 采用**单点归一化（single normalization point）**设计：resolveId钩子（及其默认实现path.resolve()）是路径被归一化的唯一位置。解析结果成为模块 ID 后，被用于所有下游场景——模块图、缓存、graph.watchFiles、插件钩子等。

关键事实：Module ID 使用操作系统原生分隔符。在 Windows 上，模块 ID 包含\分隔符（例如D:\project\src\main.js），path.resolve()的输出原样存储，不对模块 ID 应用任何分隔符归一化。

Rollup 确实有一个把\转为/的normalize函数（位于rollup/src/utils/path.ts）：

const BACKSLASH_REGEX = /\\/g; export function normalize(path) { return path.replace(BACKSLASH_REGEX, '/'); }

但该函数只在下游/输出上下文（downstream/output contexts）中使用，而非核心模块 ID 流水线：

• pluginFilter.ts—— 在匹配 include/exclude 模式前归一化 ID；
• Chunk.ts—— 生成preserveModules的 chunk 文件名；
• renderChunks.ts—— source map 的源路径；
• relativeId.ts—— 计算相对导入路径；
• MetaProperty.ts——import.meta相对路径。

而addWatchFile()这类插件 API不做任何归一化——它信任调用方提供与模块 ID 约定一致的路径。

Rolldown 当前实现：ModuleId 的三分类设计

Rolldown 的ModuleId定义于 crates/rolldown_common/src/types/module_id.rs，其内部是一个Repr枚举，在构造时按字符串形态分为三类：

// crates/rolldown_common/src/types/module_id.rs pub struct ModuleId { repr: Repr } enum Repr { Path(ArcStr), // absolute filesystem path — path operations are meaningful Virtual(ArcStr), // virtual id, prefixed with `\0` (Rollup convention) Bare(ArcStr), // bare specifier (`react`), URL, data URI, relative specifier, … }

分类逻辑（源码classify函数）非常直观：

fn classify(inner: ArcStr) -> Repr { if inner.starts_with('\0') { Repr::Virtual(inner) } else if Path::new(inner.as_str()).is_absolute() { Repr::Path(inner) } else { Repr::Bare(inner) } }

即：以\0开头 → 虚拟模块；绝对路径 → 真实文件路径；其余（裸说明符如react、URL、data URI、相对说明符）→ 其他。

相等性、哈希与排序仍按原始字符串

关键设计点是：ModuleId的PartialEq、Ord、Hash实现全部基于as_str()的原始字符串字节比较，忽略 kind 判别值。这意味着：

• 一个ModuleId与其字符串的哈希完全相同；
• 通过impl Borrow<str>（源码第 239 行），&str可以直接作为HashMap<ModuleId, _>的查找键——map.get("/some/path")无需先构造ModuleId；
• 相同的字符串永远分类到同一个变体，以ModuleId为键的映射保持一致。

分类只"门控"路径逻辑

分类的作用是让路径操作只对真正的路径执行，避免把每个 ID 都当作路径往返Path/to_string_lossy：

• as_path()仅对Path种类返回Some(&Path)（这是一个零成本的Path::new视图），虚拟 ID、裸说明符、URL 等返回None；
• is_in_node_modules()、representative_name()等辅助方法建立在该门控之上；
• 命名（naming）是一种启发式而非路径操作，因此representative_name()不依赖is_path——例如虚拟模块\0…/empty.js?x仍会产出empty这个名字，与历史行为一致；
• new_empty()构造browser: false被忽略模块的哨兵 ID（前缀\0rolldown/empty.js?），保留原解析路径以便区分每个被忽略的模块。

与 Rollup 的对比

解析器（oxc_resolver）返回PathBuf，Rolldown 通过full_path().to_str()转为字符串后原样存储，不做分隔符归一化。在 Windows 上，模块 ID 包含原生\分隔符，并被归类为Path种类。

Rollup 与 Rolldown 在此保持一致——两者都按原样存储path.resolve()/ 解析器输出，使用原生 OS 分隔符。Rollup 的normalize函数只在下游/输出上下文生效（见上文），不作用于模块 ID。

需要说明的是：某些插件在字符串匹配模块 ID 时可能内部假设/分隔符。这是插件层面的关注点，而非 Rollup 与 Rolldown 的行为分歧。

StableModuleId：跨机器稳定的 ID

StableModuleId定义于 crates/rolldown_common/src/types/stable_module_id.rs，是ModuleId的稳定化版本：相对 cwd（当前工作目录）、使用正斜杠归一化。用于需要跨机器稳定的场景——source map、HMR 客户端的模块引用。

// Absolute → relative from cwd, forward slashes // "\0foo" → "\\0foo" (virtual module escape) // "fs" → "fs" (non-path specifiers unchanged)

其构造逻辑基于ModuleId已完成的分类（源码StableModuleId::new）：

• ModuleIdKind::Path（绝对路径）→ 通过relative_path_to_slash转为相对 cwd 的正斜杠路径；
• ModuleIdKind::Virtual（虚拟模块）→ 将\0前缀转义为\\0；
• ModuleIdKind::Bare（裸说明符 / URL 等）→ 原样返回（廉价的Arc克隆）。

仓库自带的单元测试（stable_module_id.rs中test_stabilize_id）给出了精确的预期行为：

// absolute path → relative to cwd StableModuleId::with_str(cwd.join("src").join("main.js"), &cwd).as_str() == "src/main.js" StableModuleId::with_str(cwd.join("..").join("src").join("main.js"), &cwd).as_str() == "../src/main.js" // non-path specifier → unchanged StableModuleId::with_str("fs", &cwd).as_str() == "fs" StableModuleId::with_str("https://deno.land/x/oak/mod.ts", &cwd).as_str() == "https://deno.land/x/oak/mod.ts" // virtual module → escaped StableModuleId::with_str("\0foo", &cwd).as_str() == "\\0foo"

路径身份在哪些子系统起作用

下表汇总了各子系统使用的键类型、归一化策略与风险点（源自原设计文档）：

以 crates/rolldown/src/types/scan_stage_cache.rs 为例，可以看到两条路径索引的实际形态：

// Usage: Map file path emitted by watcher to corresponding module index pub module_idx_by_abs_path: FxHashMap<ArcStr, ModuleIdx>, // Usage: Map module stable id injected to client code to corresponding module index pub module_idx_by_stable_id: FxHashMap<StableModuleId, ModuleIdx>,

其中module_idx_by_abs_path在插入时做了normal_module.id.as_arc_str().to_slash()归一化（build_module_index_maps与merge两处），把原生分隔符统一为正斜杠——这正是为了让 HMR 中由 watcher 报告的文件变更路径（同样经to_slash()）能够精确匹配。在 crates/rolldown/src/hmr/hmr_stage.rs 的compute_hmr_update_for_file_changes中可以看到完整的对照流程：watcher 传来的changed_file_path先to_slash()，再作为键查询module_idx_by_abs_path定位受影响的模块；插件hotUpdate钩子返回的 ID 也以同样的to_slash()方式归一化后回查。

而add_watch_file()在 crates/rolldown_plugin/src/plugin_context/plugin_context.rs 等四处插件上下文中均直接接收&str存储，不做任何归一化——插件必须自行保证与模块 ID 约定一致，这与 Rollup 的行为对齐。

现有的归一化工具

自 sugar_path 3 起，推荐统一使用 crates/rolldown_std_utils/src/path_ext.rs 中的辅助函数，而不是在调用点手写sugar_path组合（避免重新引入relative(...).to_slash_lossy().into_owned()这类有损或双重分配链条）：

• relative_path_to_slash(target, base)—— 从base到target的词法相对路径，输出/分隔的 UTF-8 字符串；
• relative_path_as_js_specifier(target, base)—— 格式化为 JS 风格的相对说明符：相同路径 →"."，离开 base（..开头）→ 原样，否则 →"./…"；
• absolute_path_to_relative_slash(path, cwd)—— 绝对路径转相对 cwd 的正斜杠路径（稳定 ID / 诊断用）；
• normalize_path_buf_to_slash(path)—— 归一化自有路径后转为正斜杠字符串（join产物首选，消费型链避免拷贝）；
• path_buf_to_slash(path)、absolutize_path_buf(path)、strip_path_prefix_to_slash(path, prefix)等。

这些工具遵循一个贯穿 Rolldown 的不变量：模块与文件系统路径已知为合法 UTF-8，因此使用expect_to_str()/expect_to_slash()这类严格转换（非法 UTF-8 时 panic），而非有损的to_string_lossy()。完整的工具族清单见 crates/rolldown_std_utils/src/lib.rs，风格指南见 internal-docs/path-manipulation/style-guide.md。

核心问题：四处路径来源的表示不一致

模块 ID 是字符串，而系统中不同部分产生路径字符串的方式不同：

1. Resolver（解析器）—— 产生绝对路径（平台原生分隔符）；
2. Plugins（插件）—— 通过addWatchFile()提供路径（不保证归一化）；
3. notify crate—— 报告 OS 原生路径的文件变更事件；
4. HMR client—— 发送稳定 ID（相对路径 + 正斜杠）。

如果任意两方对同一文件的表示方式不一致，查找就会静默失败：模块找不到、缓存未命中、watch 文件匹配不上、HMR 更新被丢弃——没有任何显式报错。

当前之所以"大体能工作"，是因为解析器自洽（resolver is consistent with itself），且大多数查找在两侧都使用解析器输出。脆弱点集中在边界（boundaries）——外部产生的路径（notify 事件、插件输入、HMR 客户端）与解析器产生的模块 ID 进行比较的地方。

PathBuf 的比较行为：组件比较而非字节比较

Path/PathBuf的比较基于组件（components）而非原始字节。根据 Rust 官方文档，归一化忽略"重复分隔符、非开头的.组件、尾部分隔符"；在 Windows 上，/和\都被视为分隔符。因此字符串相等与PathBuf相等在以下场景中表现不同：

哈希与相等性一致——因此PathBuf可以安全地用于HashSet/HashMap。

局限性：PathBuf比较不解析..段，也不解析符号链接。要处理这两者需要fs::canonicalize()，但它有自己的代价：会解析符号链接，且对不存在的路径可能失败。

这一差异正好解释了设计文档表格中"解析器包缓存使用PathBuf组件比较"能处理分隔符差异的原因——解析器内部对同一路径的不同分隔符写法可以正确命中同一缓存项，而字符串键的模块图则必须依赖解析器输出的一致性。

未解决的问题

原设计文档明确列出三个悬而未决的问题，可作为理解当前实现边界的参考：

• 是否应在创建时归一化模块 ID？Rollup 不归一化模块 ID 分隔符——在 Windows 上插件看到的是带\的 ID。Rolldown 目前对齐该行为。若 Rolldown 选择在ModuleId::new()中统一归一化为/，会改变 Windows 上可观察到的模块 ID，但可能简化插件过滤器匹配和内部比较。

• watch 文件集合是否应改用PathBuf而非ArcStr？PathBuf能处理尾部斜杠、双斜杠、.段和 Windows 分隔符；代价是失去廉价的ArcStr克隆和&str查找。watch 专属讨论见 internal-docs/watch-mode/implementation.md。

• ..段与符号链接——PathBuf比较和字符串比较都无法处理这两者。实际上，..不应出现在解析器输出中（解析器会 canonicalize），符号链接是罕见边界情况。Rolldown 是否应对此做出任何保证？

深入阅读

• internal-docs/module-id/implementation.md —— 本文对应的原始设计文档
• crates/rolldown_common/src/types/module_id.rs ——ModuleId类型（三分类、Borrow<str>查找、相等性实现）
• crates/rolldown_common/src/types/stable_module_id.rs ——StableModuleId类型及其单元测试
• crates/rolldown_std_utils/src/path_ext.rs —— 路径归一化工具族（relative_path_to_slash、relative_path_as_js_specifier等）
• crates/rolldown/src/types/scan_stage_cache.rs ——module_idx_by_abs_path/module_idx_by_stable_id两条路径索引的实际定义与构建
• crates/rolldown/src/hmr/hmr_stage.rs —— HMR 中文件变更路径与模块 ID 的匹配流程
• crates/rolldown_plugin/src/plugin_context/plugin_context.rs ——add_watch_file()插件 API
• internal-docs/watch-mode/implementation.md —— watch 文件集合的路径匹配讨论
• internal-docs/path-manipulation/style-guide.md —— 路径操作风格指南

【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown