Rolldown Rust Crates 使用指南：面向 crates.io 的 Rust API 与维护策略解析

Rolldown Rust Crates 使用指南面向 crates.io 的 Rust API 与维护策略解析【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown本篇技术指南以官方文档 docs/apis/rust-crates.md 为骨架系统介绍 Rolldown 以 Rust crate 形式发布在 crates.io 上的使用方式包括rolldown主 crate 的核心 API、以 workspace 形式组织的大量rolldown_*内部 crate 体系以及项目对 Rust crate 明确的维护策略不遵循 semver、不提供文档、不承接 Rust-only issue。读完本文你将清楚知道如何在自己的 Rust 工程中引入并调用 Rolldown 的 Rust API也了解在何种场景下更适合使用官方聚焦维护的 JS 包。一、Rolldown 的双重发布形态JS 包之外还有 Rust crateRolldown 是一个使用 Rust 编写的 JavaScript/TypeScript 打包器对外提供 Rollup 兼容的 API。大多数用户接触的是 npm 上的 JS 包如rolldownnpm 包而官方文档 docs/apis/rust-crates.md 明确指出Rolldown is also provided as a Rust crate on crates.io.也就是说Rolldown 同时以 Rust crate 的形式发布到 crates.io允许 Rust 开发者绕过 Node/napi 绑定层直接以 Rust 库的方式调用打包能力。主 crate 名为rolldown其Cargo.toml中的描述为 Fast JavaScript bundler in Rust, designed for the future of Vite版本与 workspace 同步为1.2.7见 crates/rolldown/Cargo.toml。在仓库的 根 Cargo.toml 中可以看到这是一个标准的 Cargo workspacemembers [./crates/*, tasks/*]其中所有内部 crate 均以path指向本地源码、以版本号对齐 workspace 版本。Rust 生态使用者真正需要关心的是对外发布的rolldowncrate而rolldown_common、rolldown_plugin、rolldown_resolver等其余 crate 主要是内部实现模块部分也声明了publish但从维护策略看并不面向外部用户提供稳定承诺。二、核心内容三条维护策略必须在使用前理解官方文档 docs/apis/rust-crates.md 用整节篇幅强调在使用 crates 之前务必先理解以下维护策略。这是本文最需要被继承并强调的实战信息crates 不遵循 semver 契约。任意版本中都可以自由引入破坏性变更Breaking changes may be introduced freely in any version。这意味着你不能依赖语义化版本号来判断兼容性升级依赖时必须自行阅读 changelog 或源码。crates 不提供文档The documentation for the crates will not be provided。Rust 侧的 API 没有官方文档承诺读者需要直接阅读源码或参考 docs/apis 下的 API 文档与示例。仅影响 Rust crates 的 issue 不会被团队处理会被直接关闭但团队欢迎针对这些用例提交 Pull RequestAny issues that only affect for the Rust crates will not be worked on as a team and will be closed. That said, we will accept pull requests for those use cases。文档还解释了这些策略的动机JS 包是项目的关注焦点团队希望尽可能降低 crates 的维护成本。同时文档留有一个开放口子——如果出现长期稳定的贡献者愿意接手这一领域团队对重新审视后两条策略持开放态度。三、如何在 Rust 工程中使用rolldowncrate1. 添加依赖在Cargo.toml中加入[dependencies] rolldown 1.2.7从 crates/rolldown/Cargo.toml 的源码可以看到rolldowncrate 定义了如下 feature 开关[features] default [serde] serde [dep:serde, oxc_index/serde] testing [] experimental []serde默认开启为相关类型启用serde序列化/反序列化能力依赖可选依赖serde与oxc_index/serde。若不需要序列化配置对象可通过default-features false关闭以减小依赖面。testing开启后额外导出内部测试辅助函数例如 crates/rolldown/src/lib.rs 中#[cfg(feature testing)] pub use crate::utils::determine_minify_internal_exports_default;仅供测试场景使用。experimental开启实验性 API例如增量构建incremental build相关方法incremental_write/incremental_generate等见 crates/rolldown/src/bundler/impl_bundler_build.rs 中的#[cfg(feature experimental)]分支。该 feature 未承诺稳定API 可能随时变动。此外该 crate 设置了doctest false见同一 Cargo.toml 的[lib]段即不运行 doc-test这与“不提供文档”的维护策略一致也从侧面说明 API 注释并非官方承诺。2. 最小可用示例仓库提供了可直接运行的官方示例 crates/rolldown/examples/basic.rs它演示了rolldowncrate 最核心的用法。完整代码如下use rolldown::{Bundler, BundlerOptions, InputItem, SourceMapType}; use rolldown_workspace as workspace; use sugar_path::SugarPath; // cargo run --example basic #[tokio::main] async fn main() { let mut bundler Bundler::new(BundlerOptions { input: Some(vec![ ./entry.js.to_string().into(), InputItem { import: ./other-entry.js.to_string(), ..Default::default() }, InputItem { name: Some(third-entry.to_string()), import: ./third-entry.js.to_string() }, ]), cwd: Some(workspace::crate_dir(rolldown).join(./examples/basic).normalize().into_owned()), sourcemap: Some(SourceMapType::File), ..Default::default() }) .expect(Failed to create bundler); let _result bundler.write().await.unwrap(); }这个示例覆盖了三个关键点Bundler::new(BundlerOptions)构造打包器实例。BundlerOptions是入口配置结构体实现了Default可用..Default::default()只覆盖关心的字段多入口声明input字段接受VecInputItem其中InputItem支持仅传import路径也支持附加name自定义入口名name: Some(third-entry.to_string())会生成名为third-entry的入口 chunk异步构建 APIbundler.write().await执行完整构建并把产物写入磁盘示例配合#[tokio::main]在 tokio 运行时中运行。注意构建调用返回BuildResult错误处理建议使用?或expect显式处理。3. 核心 API 一览从 crates/rolldown/src/lib.rs 的公开导出可以看出 crate 对外暴露的核心类型pub use crate::{ bundle::{bundle::Bundle, bundle_factory::{BundleFactory, BundleFactoryOptions}, bundle_handle::BundleHandle}, bundler::Bundler, bundler_builder::BundlerBuilder, types::{bundle_output::BundleOutput, bundler_config::BundlerConfig}, }; pub use rolldown_common::bundler_options::*; pub use rolldown_resolver::ResolveOptions; pub use rolldown_plugin as plugin;Bundler最常用的入口类型。Bundler::new(options)创建实例write()/generate()执行构建。从源码 crates/rolldown/src/bundler/bundler.rs 可见其内部委托给BundleFactory并维护ScanStageCache供增量构建使用调用write()/generate()会触发closeBundle前的生命周期管理ensure_last_bundle_closed并可用close()显式关闭会触发closeBundle插件钩子。BundlerOptions配置结构体定义于 crates/rolldown_common/src/inner_bundler_options/mod.rs字段与 JS 侧 Rollup 风格选项一一对应例如输入侧inputVecInputItem、cwd、external、platform、shim_missing_exports输出侧name、entry_filenames、chunk_filenames、asset_filenames、dir、file、format、exports、globals、sourcemap、banner/footer/intro/outro等 addon 选项、hash_characters、module_types解析与优化resolveResolveOptions、treeshake、minify、define、inject、keep_names、external_live_bindings实验项experimentalExperimentalOptions。 借助serdefeature该结构体还支持反序列化配置为 camelCase 命名、未知字段报错可用于从 JSON 配置直接构造。BundlerBuilder链式构建器见 crates/rolldown/src/bundler_builder.rs提供with_options(options)、with_plugins(plugins)最终build()返回BuildResultBundler适合需要注入插件列表的场合。BundlerConfig组合配置结构体见 crates/rolldown/src/types/bundler_config.rs同时持有options: BundlerOptions与plugins: VecSharedPluginable供Watcher等需要内部构造 bundler 的 API 使用。pluginrolldown_plugin模块的再导出Rust 侧同样可以编写或注入插件。4. 构建流程的底层调用链从源码结构看一次write()调用会依次经过Bundler::write()crates/rolldown/src/bundler/impl_bundler_build.rs关闭上一个 bundle、按需进入增量构建分支然后通过BundleFactory创建BundleBundle::write()crates/rolldown/src/bundle/bundle.rs触发BuildStarttrace 事件执行ScanStage扫描模块图、规范化输出并更新缓存随后进入 Link 与 Generate 阶段输出写入计算dist_dir cwd.join(out_dir)支持clean_dir清理、NUL 字节文件名校验、目录自动创建最后写出所有 chunk/asset 并调用writeBundle插件钩子。其中generate()与write()的区别在于generate()只生成产物到内存BundleOutput而不落盘。BundleOutput通过output.assets暴露生成的文件列表这在需要把产物交给自定义发布流程时非常实用。另外 crates/rolldown/src/bundle/bundle.rs 中is_filename_outside_output_dir的单元测试表明产物文件名若解析到输出目录之外如../file、/file、Windows 盘符路径等会被拒绝这是 Rust API 内置的安全防护。四、与 JS 包的关系定位差异与使用建议结合维护策略可以得出清晰的定位结论面向生产使用的首选是 JS 包。团队将维护精力集中在 JS 侧API 稳定与文档质量都有保障且 Rollup 兼容 API 是设计目标Rust crate 适合对性能敏感、需要把打包能力嵌入 Rust 工具链的场景例如构建自己的 CLI、编辑器插件或服务端构建服务但必须接受“无 semver 保证、无文档、仅 Rust 相关的问题需自行通过 PR 修复”的成本若你需要在 Rust 侧稳定消费 Rolldown建议固定版本1.2.7或 lockfile 锁定并在升级时以 CHANGELOG.md 与源码 diff 为准而不是信任版本号。五、总结Rolldown 在 crates.io 上以rolldown为主 crate 发布了完整的 Rust 打包 API包含Bundler/BundlerBuilder/BundlerConfig/BundlerOptions等核心类型支持多入口、sourcemap、插件注入与异步构建。但官方在 docs/apis/rust-crates.md 中明确限定了维护边界不遵循 semver、不提供文档、不承接仅影响 Rust crate 的 issue。理解这三条策略是在自己的 Rust 工程中正确评估、引入与升级rolldowncrate 的前提——本指南给出的依赖配置、feature 说明与最小示例可帮助你在仓库源码之外快速上手 Rust API 的实际使用。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考