rolldown 长生命周期 Bundler 架构解析:跨构建缓存、增量构建与 close 生命周期设计

原创2026-09-14 12:15:551,985 阅读
文章标签:前端构建构建工具开发工具CLI

rolldown 长生命周期 Bundler 架构解析:跨构建缓存、增量构建与 close 生命周期设计

本篇技术指南深入剖析 rolldown(Rust 编写的 JS/TS bundler)核心架构中的 Bundler 组件——它是 watch 模式、dev 模式与 HMR 共用的长生命周期、跨构建保缓存的打包器。读完本文,你将掌握 Bundler 与 Bundle、BundleFactory、ScanStageCache 之间的职责划分与调用链,理解 with_cached_bundle_experimental 增量构建的执行流程,以及 closeBundle 插件钩子为何应从 Bundler 迁移到 BundleHandle 的设计考量,并能基于仓库源码逐行印证这些机制。

本文以仓库文档 internal-docs/rust-bundler/implementation.md 为主体骨架,结合 crates/rolldown/src/bundler/ 与 crates/rolldown/src/bundle/ 下的实际实现展开。

一、Bundler 的定位:与 ClassicBundler 的根本区别

Bundler 是常驻内存、跨构建保留缓存的打包器,服务于 watch 模式、dev 模式与 HMR。它每次构建创建一个 Bundle 实例,但扫描阶段(scan stage)的缓存与 resolver 状态会跨构建持久化。

这与 ClassicBundler 形成鲜明对比:后者(Rollup API 兼容包装器)每次构建都会创建全新的 factory,不共享任何状态。两者详细对比可参阅 internal-docs/rust-classic-bundler/implementation.md。

一句话概括:Bundler 负责"跨构建"的长期状态管理,Bundle 负责"单次构建"的短期执行,ClassicBundler 则是面向 Rollup 兼容 API 的无状态外壳。

二、结构体与持久状态(Struct & Persistent State)

Bundler 的定义位于 crates/rolldown/src/bundler/bundler.rs#L15-L21:

pub struct Bundler {
  pub(super) session: rolldown_devtools::Session,
  pub(super) bundle_factory: BundleFactory,
  pub(super) cache: ScanStageCache,
  pub(super) closed: bool,
}

各字段的职责如下:

字段 类型 职责
session rolldown_devtools::Session devtools 调试会话(Bundler::new 默认创建 dummy session)
bundle_factory BundleFactory 跨构建复用,持有共享 resolver、plugin driver factory、file emitter 与 options;每次构建通过 factory.create_bundle() 产出全新的 Bundle 而不丢弃 factory 本身
cache ScanStageCache 跨构建持久化模块图、barrel 状态与模块索引映射;通过 with_cached_bundle() 换入/换出 Bundle,使增量构建只重扫变化的模块
closed bool 文档标注的"legacy 标志",详见下文"Close 机制"章节

2.1 Bundler 直接解引用到 BundleFactory

Bundler 实现了 Deref<Target = BundleFactory>(bundler.rs#L7-L13),因此调用方可以直接访问 factory 的字段,例如 bundler.options、bundler.resolver、bundler.last_bundle_handle 等,无需逐层解包。

2.2 BundleFactory 内部持有的共享状态

查看 crates/rolldown/src/bundle/bundle_factory.rs#L35-L59 可知,BundleFactory 除了文档提到的 resolver、plugin driver factory、file emitter 与 options 外,还维护以下跨构建状态:

  • module_infos_for_incremental_build:跨多个 plugin driver 共享的模块信息表,服务于增量构建;
  • transform_dependencies_for_incremental_build:为 HMR 保留来自 addWatchFile 的 transform 依赖;
  • bundle_id_seed:为每次 bundle 生成唯一 build id(generate_unique_bundle_span);
  • last_bundle_handle:最近一次构建的 BundleHandle,用于在构建后调用清理钩子;
  • lazy_compilation_context:懒编译(lazy compilation)上下文(若启用)。

其中 create_bundle()(bundle_factory.rs#L109-L137)体现了关键语义:完整构建(full build)会就地清空共享的模块信息集(module_infos_for_incremental_build.clear()),而不是替换引用,这样 dev engine 持有的长生命周期句柄仍能观察到当前构建的数据。

2.3 ScanStageCache 的持久化内容

ScanStageCache 定义于 crates/rolldown/src/types/scan_stage_cache.rs#L22-L42,是增量构建的核心数据结构:

  • snapshot: Option<NormalizedScanStageOutput>:最近一次构建的规范化扫描输出快照,是增量构建的基线;
  • barrel_state:barrel(桶文件)解析状态;
  • module_id_to_idx:模块 id 到模块索引的映射;
  • importers:每个模块的 importer 记录;
  • modules_with_changed_importers:部分扫描中被修改了 importer 记录的模块集合;
  • pending_rescans:中止(并回滚)的部分扫描遗留文件,下次部分扫描会重试;
  • user_defined_entry:用户定义入口模块集合;
  • module_idx_by_abs_path / module_idx_by_stable_id:watcher 文件路径 / 注入客户端的 stable id 到模块索引的映射。

merge() 方法(scan_stage_cache.rs#L123-L306)负责把部分扫描的新结果合并进快照:更新 module_table、维护 TLA 模块计数、重建 importer 集合、清理已删除的动态入口等,保证缓存始终是一个可继续增量构建的有效图。

三、构建生命周期:with_cached_bundle_experimental 的四步流程

每次构建都经由 with_cached_bundle_experimental 完成缓存换入换出。其核心实现位于 crates/rolldown/src/bundler/impl_bundler_incremental_build.rs#L16-L39:

pub(crate) async fn with_cached_bundle<T>(
  &mut self,
  bundle_mode: BundleMode,
  with_fn: impl AsyncFnOnce(&mut Bundle) -> BuildResult<T>,
) -> BuildResult<T> {
  let cache = mem::take(&mut self.cache);
  let mut bundle = self.bundle_factory.create_bundle(bundle_mode, Some(cache))?;
  let ret = with_fn(&mut bundle).await;
  self.cache = bundle.cache;
  ret
}

执行流程:

  1. 取出缓存:用 mem::take 把当前 ScanStageCache 从 self 中取出;
  2. 创建 Bundle:调用 bundle_factory.create_bundle(bundle_mode, Some(cache)) 产出 Bundle;
  3. 执行闭包:把 &mut Bundle 传给闭包,由调用方编排 scan / render / write 各阶段;
  4. 归还缓存:闭包返回后,把 bundle.cache 存回 self。

值得注意的是第 28-29 行:构建结果无论成败都必须把缓存移回 Bundler。若在 Err 路径上提前 ? 返回,bundle 会被 drop,Bundler::cache 将停留在 mem::take 安装的 default()(snapshot = None),导致下一次 HMR 周期在 get_snapshot() 处 panic。这正是文档引用的缓存完整性约束(详见 internal-docs/bundler-data-lifecycle/implementation.md 中 "Cache integrity on a failed build" 一节)。

3.1 watch 模式闭包的典型编排

watch 模式的闭包通常如此组织(即文档给出的模式):

bundler.with_cached_bundle_experimental(FullBuild, |bundle| async {
    let scan_output = bundle.scan_modules(scan_mode).await?;
    // register FS watches from bundle.get_watch_files() BEFORE render
    let output = bundle.bundle_write(scan_output).await?;
    Ok(output)
}).await

关键点在于:必须在 render 之前注册 FS watch。这样 render 阶段钩子(例如 renderStart 修改了某个文件)产生的变化也能被 FS watcher 捕获,避免遗漏触发重建。

3.2 BundleMode 的三种模式

with_cached_bundle_experimental 的 bundle_mode 参数来自 crates/rolldown_common/src/types/bundle_mode.rs#L3-L11:

pub enum BundleMode {
  FullBuild,            // 普通完整构建,不写入缓存
  IncrementalFullBuild, // 开启 incremental 选项的完整构建,会把数据存入缓存供后续增量构建使用
  IncrementalBuild,     // 仅针对变更文件的增量构建
}

其中 is_full_build() 匹配 FullBuild | IncrementalFullBuild,is_incremental() 匹配 IncrementalFullBuild | IncrementalBuild。增量构建路径(impl_bundler_incremental_build.rs#L55-L78)会根据当前是否有快照决定扫描模式:没有快照就降级为 ScanMode::Full,否则采用部分扫描。

四、Bundle:单次构建的执行载体

Bundle 定义于 crates/rolldown/src/bundle/bundle.rs#L31-L40:

pub struct Bundle<Fs: FileSystem + Clone + 'static = OsFileSystem> {
  pub(crate) fs: Fs,
  pub(crate) options: SharedOptions,
  pub(crate) resolver: SharedResolver<Fs>,
  pub(crate) file_emitter: SharedFileEmitter,
  pub(crate) plugin_driver: SharedPluginDriver,
  pub(crate) warnings: Vec<BuildDiagnostic>,
  pub(crate) cache: ScanStageCache,
  pub(crate) bundle_span: tracing::Span,
}

Bundle 代表一次构建。它有一组消费型方法——write()、generate()、scan(),均通过 mut self 拿走 self 的所有权,从而在类型层面强制"单次使用"语义,防止重复调用:

针对 watch 模式,还提供一组非消费型方法——scan_modules()、bundle_write()、bundle_generate()、get_watch_files(),允许通过 with_cached_bundle_experimental 手动编排各阶段(这正是 watch 闭包在 scan 与 render 之间插入 FS watch 注册的前提)。

此外,Bundle::context()(bundle.rs#L159-L165)在消费 Bundle 前提取出 BundleHandle,让调用方在 bundle 被消费后仍能访问 watch files、plugin driver 与 options(见下文第五节)。

bundle_write 内部还包含产物写出细节:按 clean_dir 选项清理输出目录、校验文件名中不允许出现 NUL 字节(对应 output.entryFileNames / output.chunkFileNames / output.assetFileNames 模式)、逐 chunk 建目录写文件、最后调用 writeBundle 钩子。

五、Bundler 不需要 close():生命周期职责的重新划分

文档明确提出了一个重要的设计论断:Bundler 是长生命周期的 Rust 结构体,资源在 drop 时自动清理,不存在需要"显式关闭"的东西。

当前 Bundler::close()(位于 crates/rolldown/src/bundler/impl_bundler_build.rs#L55-L66)实际做的工作只有两件:

  1. 调用 closeBundle 插件钩子——但这属于单次构建的生命周期问题,应挂在构建产物(BundleHandle)上,而非 bundler 上;
  2. 重置 scan stage 缓存、清空 resolver 缓存——但这些属于重建(rebuild)关注点,不是关闭关注点。在 watch 模式下,result.close() 时销毁缓存反而是有害的(会强制一次冷构建)。

5.1 应从 Bundler 移除的成员

文档列出了以下应当移除的成员及其理由:

  • closed 标志:一旦 closeBundle 迁到 BundleHandle,该标志便失去意义(当前源码中该字段仍存在于 bundler.rs#L20,属于尚未完成的迁移);
  • inner_close():其唯一实质工作(调用 closeBundle)将迁至 BundleHandle.close();缓存/resolver 清理在 drop 时自然完成;
  • reset_closed_for_watch_mode():这个 hack 之所以存在,是因为 BindingWatcherBundler.close() 调用 bundler.close() 会置 closed = true,每次重建前需要重置。若 closeBundle 移到 BundleHandle,则无需重置;
  • create_error_if_closed():需要关闭守卫的调用方(ClassicBundler、DevEngine)都有各自的 closed 标志(当前 Bundler::write/generate/scan 仍通过 bundler.rs#L47-L52 的 create_error_if_closed 做守卫,并在 impl_bundler_build.rs#L21-L53 中被调用);
  • close():整体移除。

5.2 BundleHandle.close() 的设计决策

文档给出的目标设计是让 BundleHandle 拥有 close() 方法,要求:

  1. 调用 closeBundle 插件钩子;
  2. 幂等——重复调用是安全的(第二次调用为 no-op),通过 Arc<AtomicBool> 跟踪。

这一设计在当前源码中已经落地。crates/rolldown/src/bundle/bundle_handle.rs#L71-L78:

pub async fn close(&self) -> anyhow::Result<()> {
  if self.closed.swap(true, Ordering::SeqCst) {
    return Ok(());
  }
  self.plugin_driver.close_bundle(None).await?;
  self.plugin_driver.clear();
  Ok(())
}

swap(true, Ordering::SeqCst) 保证了原子幂等:首次调用返回 false 才真正执行 closeBundle 并清理 plugin driver,后续调用直接短路返回。

为什么这是正确的位置? 因为 closeBundle 语义是"该次构建不再有任何输出处理":

  • watcher 的 BUNDLE_END / ERROR 事件数据携带的是 BundleHandle(而非完整 bundler);
  • JS 侧 result.close() 直接调用 handle.close(),无需获取 bundler 锁。

BundleHandle 本身是轻量句柄(options + plugin_driver + closed,三者均为 Arc 包装,可 Clone),它的定位正是解决"Bundle 被消费后仍需访问 bundle 状态"的问题:ClassicBundler 与 BundleFactory 保存最近一次的 BundleHandle 以调用清理钩子,binding 层则用它向 JS 暴露 watch files(bundle_handle.rs#L9-L42 的文档注释对此有完整阐述)。

六、与 Watcher 的关系:构建生命周期由 rolldown_watcher 拥有

rolldown_watcher 负责拥有整个构建生命周期。文档给出四个关键环节,源码在 crates/rolldown_watcher/src/watch_task.rs 中逐一印证:

  1. 每个 WatchTask 持有一个 Arc<TokioMutex<Bundler>>(watch_task.rs#L26),Bundler 通过 TokioMutex 包装以便跨异步任务安全共享;
  2. 重建时加锁并编排阶段:coordinator 锁定 bundler,调用 with_cached_bundle_experimental,在闭包内完成 scan / write 阶段(watch_task.rs#L105-L134)。闭包内还在 scan 之后、render 之前调用 bundle.get_watch_files() 收集 watch 文件,即使在 scan 报错时也先注册 watch(保证用户修复问题后能自动恢复重建);
  3. 构建后触发 closeBundle:每次构建后,rolldown_watcher 应调用 Bundle.close()(或 BundleHandle.close())来触发 closeBundle——这是 watcher 的责任,而不是 JS 侧越权去做;
  4. watcher 关闭即 drop bundler:watcher 关闭时 bundler 被 drop,资源随之释放。

由此得出一个重要结论:BindingWatcherBundler 不应该调用 bundler.close()——closeBundle 钩子是 rolldown_watcher 的契约,应在构建生命周期的正确时机触发。

文档末尾还提示,watch 模式架构与生命周期的完整展开可继续阅读 internal-docs/watch-mode/implementation.md。

七、小结与延伸阅读

本文梳理了 rolldown 长生命周期打包器 Bundler 的完整架构:

  • 职责分层:Bundler(跨构建状态)→ BundleFactory(共享基础设施)→ Bundle(单次构建执行)→ BundleHandle(消费后访问与 closeBundle 触发点);
  • 增量构建:ScanStageCache 随 with_cached_bundle_experimental 换入换出,快照保证部分扫描只重扫变更模块,失败路径也严格维护缓存完整性;
  • 生命周期重构:closeBundle 正从 bundler 级向 bundle 级迁移,BundleHandle.close() 的幂等实现已在源码落地。

感兴趣的读者可以继续深入以下源码与文档:

登录后查看全文
rolldown