rolldown 长生命周期 Bundler 架构解析:跨构建缓存、增量构建与 close 生命周期设计
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
}
执行流程:
- 取出缓存:用
mem::take把当前ScanStageCache从self中取出; - 创建 Bundle:调用
bundle_factory.create_bundle(bundle_mode, Some(cache))产出Bundle; - 执行闭包:把
&mut Bundle传给闭包,由调用方编排 scan / render / write 各阶段; - 归还缓存:闭包返回后,把
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 的所有权,从而在类型层面强制"单次使用"语义,防止重复调用:
write()(bundle.rs#L45-L59):执行全量扫描后调用bundle_write,写出产物;generate()(bundle.rs#L63-L80):扫描 +bundle_generate,仅生成不落盘;scan()(bundle.rs#L84-L88):仅执行扫描。
针对 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)实际做的工作只有两件:
- 调用
closeBundle插件钩子——但这属于单次构建的生命周期问题,应挂在构建产物(BundleHandle)上,而非 bundler 上; - 重置 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() 方法,要求:
- 调用
closeBundle插件钩子; - 幂等——重复调用是安全的(第二次调用为 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 中逐一印证:
- 每个
WatchTask持有一个Arc<TokioMutex<Bundler>>(watch_task.rs#L26),Bundler通过TokioMutex包装以便跨异步任务安全共享; - 重建时加锁并编排阶段:coordinator 锁定 bundler,调用
with_cached_bundle_experimental,在闭包内完成 scan / write 阶段(watch_task.rs#L105-L134)。闭包内还在 scan 之后、render 之前调用bundle.get_watch_files()收集 watch 文件,即使在 scan 报错时也先注册 watch(保证用户修复问题后能自动恢复重建); - 构建后触发
closeBundle:每次构建后,rolldown_watcher应调用Bundle.close()(或BundleHandle.close())来触发closeBundle——这是 watcher 的责任,而不是 JS 侧越权去做; - 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()的幂等实现已在源码落地。
感兴趣的读者可以继续深入以下源码与文档:
- crates/rolldown/src/bundler/bundler.rs — Bundler 结构体与 Deref 实现
- crates/rolldown/src/bundler/impl_bundler_incremental_build.rs —
with_cached_bundle与增量构建入口 - crates/rolldown/src/bundle/bundle.rs — Bundle 消费型/非消费型方法
- crates/rolldown/src/bundle/bundle_factory.rs — BundleFactory 与 create_bundle
- crates/rolldown/src/bundle/bundle_handle.rs — BundleHandle 与幂等 close
- crates/rolldown/src/types/scan_stage_cache.rs — ScanStageCache 结构与 merge 逻辑
- crates/rolldown_watcher/src/watch_task.rs — WatchTask 与构建编排
- internal-docs/rust-classic-bundler/implementation.md — ClassicBundler 对比
- internal-docs/watch-mode/implementation.md — watch 模式架构