Rslib Wiki

    核心构建流程

    从命令到构建

    CLI 入口位于 packages/core/bin/rslib.js，最终调用 packages/core/src/cli/index.ts 中的 runCLI。runCLI 做三件事：

    1. 初始化 NODE_ENV。build 和 inspect 默认生产模式，其他命令默认开发模式。
    2. 根据 --log-level 提前设置日志级别。
    3. 打印版本问候并注册命令。

    命令定义在 packages/core/src/cli/commands.ts。当前主要命令包括：

    命令行为关键方法
    rslib 或 rslib build生产构建，可传 --watchrslib.build
    rslib inspect输出 Rslib、Rsbuild、Rspack 配置rslib.inspectConfig
    rslib mf-dev启动 Module Federation 格式的 dev serverrslib.startMFDevServer

    CLI 参数覆盖

    packages/core/src/cli/init.ts 负责将 CLI 参数覆盖到配置上。流程如下：

    覆盖规则集中在 applyCliOptions：

    CLI 参数覆盖目标
    --format每个 lib.format
    --bundle 或 --no-bundle每个 lib.bundle
    --entry每个 lib.source.entry
    --syntax每个 lib.syntax
    --dts 或 --no-dts每个 lib.dts
    --target每个 lib.output.target
    --externals每个 lib.output.externals
    --dist-path每个 lib.output.distPath.root
    --tsconfig每个 lib.source.tsconfigPath

    parseEntryOption 支持两种 entry 写法：name=path 显式命名，或直接传路径并根据 basename 生成名称。如果多个隐式 entry basename 冲突，会追加序号。

    配置加载

    packages/core/src/loadConfig.ts 包含两个公共能力：

    • defineConfig：只做类型辅助，原样返回配置或配置函数。
    • loadConfig：查找并加载 rslib.config.*。

    默认查找顺序为：

    1. rslib.config.mjs
    2. rslib.config.ts
    3. rslib.config.js
    4. rslib.config.cjs
    5. rslib.config.mts
    6. rslib.config.cts

    如果用户显式传 --config，则只解析该路径并在不存在时报错。如果没有配置文件，CLI 会创建一个默认 config.lib = [{}]，让纯 CLI 参数也能完成构建。

    createRslib 实例

    packages/core/src/createRslib.ts 是编程式 API 的核心。它返回的 RslibInstance 包含：

    方法用途
    build生成 environments，创建 Rsbuild 实例并执行 build
    inspectConfig生成 environments 并调用 Rsbuild inspectConfig，同时返回 Rslib 原始配置
    startMFDevServer只筛选 format: "mf" 的 environments，启动 dev server
    onAfterCreateRsbuild注册 Rsbuild 实例创建后的回调
    getRslibConfig返回当前 Rslib 配置对象

    createRslib 还会处理 env 文件：

    • 当 options.loadEnv 开启时，调用 Rsbuild 的 loadEnv。
    • 将 public env vars 合并到 config.source.define。
    • 将 env file paths 存进 _privateMeta.envFilePaths，watch restart 时可纳入监听。
    • 在 build 或 dev server close 时执行 env cleanup。

    Build 流程

    Watch 模式下，CLI 会增加一个 rslib:on-after-build 插件，在首次编译后输出“watching for changes”日志。CLI 还会通过 restart.ts 监听配置文件和 env 文件变化，重启构建实例。

    Inspect 流程

    inspectConfig 的目的不是执行构建，而是让维护者看到 Rslib 经过派生后的 Rsbuild 和 Rspack 配置。它会：

    1. 设置 NODE_ENV 或指定 inspect mode。
    2. 调用 composeRsbuildEnvironments。
    3. 创建 Rsbuild 实例。
    4. 调用 rsbuildInstance.inspectConfig。
    5. 在 extraConfigs 中附带 Rslib 原始配置。
    6. 返回字符串化后的 rslibConfig 以及 Rsbuild inspect 结果。

    此外，applyDebugInspectConfigPlugin 会在 DEBUG 包含 rslib key 时自动把 Rslib、Rsbuild、Rspack 配置写入磁盘，便于定位配置派生问题。

    Module Federation Dev Server

    startMFDevServer 只针对 format: "mf"：

    1. 设置 NODE_ENV=development。
    2. 生成 environments 和带格式信息的 environment 列表。
    3. 如果传入 --lib，只选择对应 id 的 MF environment。
    4. 没有找到 MF environment 时抛出明确错误。
    5. 创建 Rsbuild dev server，并把 close 函数注册给 restart 系统。

    这一设计避免非 MF library environment 被误用于 dev server，因为普通库构建不需要 Rsbuild 应用 dev server。

    公共 API 出口

    packages/core/src/index.ts 明确定义 @rslib/core 的公共 API。维护时应把这里视为稳定边界：

    • CLI：runCLI
    • 实例：createRslib
    • 配置：defineConfig、loadConfig、loadEnv、mergeRslibConfig
    • 类型：RslibConfig、LibConfig、Format、Dts、BuildOptions 等
    • Rsbuild 透传：rsbuild namespace、Rspack、rspack、RsbuildPlugin