Core 常规讲解文档

这个目录是对 packages/core 的常规维护者文档。它把源码中分散的判断整理成主题化说明,帮助维护者先理解设计和行为边界,再回到源码定位具体实现。

推荐阅读顺序

  1. 维护者心智模型:理解 core 的职责边界、配置模型和主要抽象。
  2. 从 CLI 到 Rsbuild 的生命周期:完整串起 CLI、配置加载、Rslib 实例、Rsbuild 实例和 restart。
  3. 配置编排常规说明:解释 config.ts 为什么复杂,以及每一组 compose 函数的职责和顺序。
  4. 输出与模块格式:说明 ESM、CJS、UMD、IIFE、MF 的输出差异和维护风险。
  5. Bundleless、CSS 与资源:解释 bundleless 的 entry 展开、路径重写、CSS extract 和 asset preserve。
  6. 声明文件接入点:说明 core 如何调用 rsbuild-plugin-dts,以及 dts 配置如何跟 JS 输出保持一致。
  7. 实验性 exe 接入点:解释 core 层如何校验和挂载可执行文件生成能力。
  8. 维护与排障指南:按常见改动场景给出排查路径和测试建议。

与其他文档的关系

文档类型适合场景入口
常规讲解新维护者入门、理解设计、评估改动影响本目录
现有概要快速把握仓库和模块全貌../build-flow.md../lib-config-composition.md
深度专题理解关键机制为什么存在、改错会坏在哪里../deep-dives/

常规讲解文档会故意避免逐行复述源码,而是把源码中分散的判断整理成系统性的维护知识。