企业官网建设流程全解析

Rolldown 仓库结构解析：从 Rust 核心到 Node.js 生态的完整导航指南

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

本指南以docs/development-guide/repo-structure.md为骨架，系统梳理 Rolldown 仓库的顶层目录职责、Rust 与 Node.js 两侧的分工，以及vite/、examples/、scripts/等辅助目录的作用。读完本文，你将能够在几十个 crate 与多个 npm 包之间快速定位核心实现、插件、测试与示例代码，掌握从源码走向构建、测试与贡献的路径。

仓库顶层布局总览

Rolldown 是一个"双栈"项目：核心打包逻辑用 Rust 实现，对外则通过 Node.js 包暴露 Rollup 兼容的 API。这种架构决定了仓库按语言与职责划分成几个互不重叠的顶层目录：

其中crates与packages构成主体，二者通过 crates/rolldown_binding 这座"桥"连接：Rust 侧负责真正的解析、链接、代码生成，Node.js 侧负责 API 层、类型定义与插件生态。此外仓库根部还有internal-docs/、tasks/、rollup/、test262/等目录，本文后续会逐一说明。

/crates：Rust 工作空间

原文档指出/crates存放全部 Rust crate，并重点介绍了其中三个。结合当前仓库的 Cargo.toml（members = ["./crates/*", "tasks/*"]）可见，crates/下实际已扩展为 55 个 crate，可大致分为四层。

核心三件套：bundler、binding 与 bench

• /rolldown（核心逻辑）：即 crates/rolldown。这是 bundler 的心脏，从 lib.rs 的模块声明可以看出其内部组织：bundler（Bundler 主体）、stages（扫描/链接/生成三阶段流水线）、module_loader（模块加载）、module_finalizers（模块收尾）、hmr（热更新）、ast_scanner（AST 扫描）等。其中stages/目录下的scan_stage.rs、link_stage/、generate_stage/清晰地对应一次完整构建的三个阶段；examples/下还带有basic.rs、build_bench_rome_ts.rs、build_bench_threejs10x.rs等 Rust 侧示例。
• /rolldown_binding（Node.js 绑定胶水）：即 crates/rolldown_binding。它使用napi-rs把核心逻辑暴露给 Node.js，从 lib.rs 可以看到其通过napi_derive::napi生成绑定代码，并默认启用mimalloc作为全局分配器；src/options/下按binding_input_options、binding_output_options等组织，用于把 JS 侧选项序列化到 Rust。它正是"Rust 核心 ↔ Node.js API"之间的转换层。
• /bench（Rust 侧基准）：即 crates/bench，提供 Rust 侧的基准测试程序（benches/bench.rs），与 packages 下的 Node.js 侧基准互补，可用just bench-rust（等价于cargo bench -p bench）运行。

支撑层 crate：领域能力拆分

核心之上，仓库将不同领域能力拆成独立 crate，职责边界清晰：

• rolldown_common：共享类型与内部选项（inner_bundler_options/、types/、chunk/、module/等），是各 crate 之间的"公共语言"。
• rolldown_plugin：插件系统本体，包含plugin.rs、plugin_driver/、plugin_context/与types/。
• rolldown_resolver、rolldown_fs、rolldown_fs_watcher、rolldown_watcher：分别负责模块解析、文件系统抽象（含内存/OS 实现）、文件监视与 watch 模式。
• rolldown_ecmascript、rolldown_ecmascript_utils：ECMAScript AST 编译与工具。
• rolldown_error：构建诊断与错误类型。
• rolldown_sourcemap：sourcemap 拼接（基于string_wizard）。
• rolldown_utils、rolldown_std_utils：通用工具函数。
• string_wizard：magic-string 风格的字符串改写库。
• rolldown_tracing、rolldown_tracking_allocator、rolldown_devtools 等：可观测性与内存追踪基建。

插件 crate 与 dev 引擎

• rolldown_plugin_*系列：从 rolldown_plugin_replace（字符串替换）、rolldown_plugin_data_url（data URL 内联）、rolldown_plugin_hmr（HMR 运行时）到rolldown_plugin_vite_*（alias、json、manifest、resolve、transform、dynamic_import_vars、import_glob、web_worker_post、reporter 等），一批内置插件与 Vite 相关插件被逐一独立成 crate，并通过 Cargo.toml 的 workspace 依赖统一管理版本。
• Dev 引擎相关：rolldown_dev、rolldown_dev_common、rolldown_devtools 与 rolldown_devtools_action 共同支撑 dev server 与调试工具链。
• 测试基建：rolldown_testing、rolldown_testing_config 提供 fixture 驱动、快照与配置变体等测试设施，供crates/rolldown/tests/下的esbuild/、rolldown/、rollup/、integration/等大规模测试套件使用。

tasks/：独立可执行任务

虽然原文档只提到/crates，但从 Cargo.toml 可见 workspace 还包含根目录的 tasks 目录，其中 generator 负责重新生成各 crate 中的generated/代码（运行时助手定义、检查选项、hook 使用跟踪、错误事件分发等），ls_lint、track_memory_allocations则承担文件名规范检查与内存分配计数快照任务（对应just update-generated-code、just allocs等命令）。

/packages：Node.js 包

原文档列出了四个核心 Node.js 包，当前 packages 目录下实际有八个，按用途可分三类。

面向用户与开发者

• /rolldown（主包）：即 packages/rolldown，对外发布的 npm 包。src/下包含index.ts（公共入口）、api/、options/、plugin/、builtin-plugin/、cli/、types/等模块；根目录还维护着binding.cjs、binding.d.cts等由rolldown_binding生成的绑定产物，以及build.ts、build-binding.ts等构建脚本。tests/下存放 1400+ 个 JS/TS 测试文件，对应just test-node-rolldown。
• /bench（Node.js 侧基准）：即 packages/bench，与crates/bench呼应，提供 Node.js 视角的基准脚本（just bench-node）。
• /debug：packages/debug 提供调试辅助包，对应just build-rolldown-debug。
• /browser与/browser-tests：packages/browser 承载@rolldown/browser（WASM 绑定产物），packages/browser-tests 则在真实浏览器与 WebContainer 中冒烟测试该产物（just test-browser、just test-webcontainer）。

兼容性测试适配层

• /rollup-tests：即 packages/rollup-tests，原文档定义为"用 rolldown 运行 rollup 测试套件的适配器"。仓库根目录的rollup/子模块（见 .gitmodules）克隆 rollup 本体，此包负责将 rollup 的测试用例接入 rolldown 执行，是验证 API 兼容性的关键一环（just test-node-rollup）。
• /vite-tests：即 packages/vite-tests，脚本化地在一个共享的根目录/vitecheckout 上运行 Vite 自身测试套件，用以验证 rolldown 作为 Vite 底层 bundler 时的行为（just test-vite）。

Dev Server 测试 harness

• /test-dev-server：即 packages/test-dev-server，承载@rolldown/test-dev-server及其 300+ 测试用例，src/下包含dev-server.ts、vite-server.ts、clients.ts、middlewares/、environments/等模块，用于端到端验证 dev 模式。

/vite：共享的 Vite checkout

原文档对/vite有明确约束，这是理解它时最需要记住的三点：

1. 单一共享：它是packages/test-dev-server与packages/vite-tests共用的唯一 Vite checkout；
2. 来源与更新方式：它是 vitejs/vite，其注释详细说明了该 checkout 同时服务于 dev-server 浏览器测试与 vite-tests 的克隆源）；
3. 必须保持未修改：目录本身被 gitignore，且禁止直接编辑其中的 Vite 源码——任何针对 Vite 的改动都应走 rolldown 侧的兼容性修复，而不是就地打补丁。

这一设计让 rolldown 始终能对"最新未污染"的 Vite 进行兼容性回归，是维护 Vite 兼容 API 的基石。

/examples：各场景使用示例

原文档指出 examples 提供"如何在 Node.js 中为各种场景使用 rolldown"的示例。当前仓库包含 13 个可运行的示例工程，覆盖典型使用场景：

• 基础用法：basic-typescript（TS 入口 +rolldown.config.js）、basic-vue（Vue 场景）、styled-components-native（JSX/styled-components）。
• 进阶特性：code-splitting 与 chunk 映射、bundle analyzer、native-magic-string、isolated-declaration、lazy-compilation（含dev.config.mjs）。
• 运行时场景：hmr-raw（手写 HMR 运行时）、watch、yarn-pnp（PnP 模式）。
• 集成示范：rollup-plugin-esbuild（复用 rollup 插件）、par-plugin（并行插件，内含 babel/esbuild/noop 三个 case 与对应插件实现）。

每个示例都自带package.json与配置文件，是上手理解 API 与内置插件用法最快的入口。

/scripts：自动化任务脚本

原文档将 scripts 定义为"自动化各种任务的脚本集合"。当前其内部组织为：

• lint/：lint 相关脚本（如 index.ts）。
• meta/：元信息与常量（constants.js、utils.js）。
• misc/：杂项自动化，例如 setup-benchmark-input（准备基准输入，just setup-bench调用）、bump-version.js（版本升级，just bump-packages调用）、gen-bundler-esm-cjs-tests.mjs（批量生成 ESM/CJS 测试）、published-package-check.mjs（发布包检查）、check-wasi-binding-deps.mjs（WASI 绑定依赖检查）等。
• src/：主要自动化源码，包括 setup-vite（实现just setup-vite，用于准备/vitecheckout）、esbuild-tests（esbuild 兼容性测试的 diff 生成）与gen-debug-action-types.ts。

配合仓库根目录的 justfile 使用，绝大多数日常操作都可一键完成：just setup（首次环境初始化）、just roll（运行全部相关检查）、just build-rolldown（构建主包）、just test-rust/just test-node（分侧跑测试）。

文档与其余目录

原文档提到/web目录下包含/docs（项目文档）。从当前仓库的实际布局看，文档目录已直接位于仓库根目录 docs，内部结构包括guide/（入门指南）、apis/（Bundler API、CLI、插件 API、Rust crate 文档）、in-depth/（自动代码分割、CJS 打包、TLA、懒加载等深入主题）、builtin-plugins/（内置插件说明）、development-guide/（本文所属的构建、测试、性能分析等开发指南）、glossary/（术语表）等；docs/package.json与netlify.toml表明其由文档站框架驱动发布。此外：

• internal-docs：面向 Rolldown 内部贡献者的实现级设计文档，覆盖 bundler 数据生命周期、代码分割、chunk hash、dev engine、watch 模式、运行时助手等主题，深入阅读可与crates/源码互相印证。
• rollup 与 test262：两个 git 子模块（见 .gitmodules），分别用于 rollup 兼容性测试与 ECMAScript 标准符合性测试（crates/rolldown/tests/下的rollup.rs、test262.rs即对应入口）。
• tasks、scripts：如前所述，承担代码生成、lint 等工程任务。

导航建议：按需求选路径

• 想了解打包流程如何实现：进入 crates/rolldown/src/stages 按 scan → link → generate 三阶段阅读，再对照 internal-docs/bundler-data-lifecycle。
• 想了解Node.js API 如何映射到 Rust：从 packages/rolldown/src/index.ts 出发，沿 crates/rolldown_binding 的binding_bundler.rs、options/追到核心实现。
• 想写一个插件：参考 crates/rolldown_plugin 的接口定义与rolldown_plugin_replace等现成实现，再对照 docs/apis/plugin-api.md。
• 想跑通测试或基准：使用 justfile 中的test-rust、test-node、bench-rust、bench-node系列命令，测试用例分别集中在crates/rolldown/tests/与packages/rolldown/tests/。

以本文的目录地图为起点，配合crates/、packages/、docs/与internal-docs/之间的相互引用，你可以在几分钟内定位到任何感兴趣的功能实现与其配套测试。

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