Rslib Wiki

    维护与排障指南

    先判断改动类型

    Core 改动通常落在以下几类：

    改动类型代表文件优先测试
    CLI 参数src/cli/*core unit、CLI integration
    配置加载src/loadConfig.ts、src/cli/init.tsconfig unit、CLI integration
    配置编排src/config.ts多 format integration、inspect
    bundlelesssrc/config.ts、src/css/*、src/asset/*bundle-false、redirect、CSS、asset
    dts 接入src/config.ts、packages/plugin-dtsdts integration、plugin-dts unit
    exesrc/exe/*integration-exe
    工具函数src/utils/*对应单元测试和受影响 integration

    不要先问“改了几行”，而是先问“这个改动影响哪条用户路径”。Core 的小改动经常影响多个产物。

    修改 config.ts 的步骤

    1. 找到相关 compose 函数。
    2. 判断该函数在 composeLibRsbuildConfig merge 顺序中的位置。
    3. 检查它依赖的输入是否已经计算完成。
    4. 检查它的输出是否会被后续用户配置覆盖。
    5. 检查是否需要删除或重置用户 config 中的原字段。
    6. 增加 inspect 或产物断言测试。

    例如修改 externals，就不能只改 composeExternalsConfig。还要检查：

    • autoExternal 是否仍正确排除用户 external keys。
    • externalsWarnConfig 是否还能先触碰 request。
    • bundleless external 是否仍在最后。
    • target externals 是否仍保留 Node builtins。

    修改 bundleless 的步骤

    Bundleless 改动必须从 entry 和路径两个维度看。

    Entry 维度：

    • glob 是否正确展开。
    • dts 文件是否过滤。
    • outBase 是否正确。
    • entry name 是否保留目录。
    • CSS entry 是否带标记。

    路径维度：

    • 源文件 import 是否被 rewrite 到输出路径。
    • 无扩展名 import 是否补扩展名。
    • TS 扩展名是否改成 JS 扩展名。
    • CSS Modules 是否指向 JS 文件。
    • 全局 CSS 是否指向 .css。
    • asset import 是否符合 redirect 配置。

    排查 bundleless 问题时，优先看 dist 内文件结构和产物内部 import，而不是只看 Rspack config。

    修改 CSS 的步骤

    CSS 改动至少检查三类输入：

    1. 全局 CSS。
    2. CSS Modules。
    3. CSS 中的资源 url。

    再检查四类配置：

    1. output.cssModules.auto。
    2. redirect.style.path。
    3. redirect.style.extension。
    4. banner.css 和 footer.css。

    如果涉及预处理器，还要验证 sass、less、stylus 规则是否仍能匹配。pluginLibCss 中有对 sass-1、less-2 这类 rule id 后缀的兼容逻辑，不要轻易删除。

    修改 asset 的步骤

    Asset 改动要区分 issuer：

    • JS issuer。
    • CSS issuer。
    • SVGR issuer。
    • ?url query。

    常见排查方法：

    1. 看 Rspack rule 是否被拆成 JS 和 CSS 两个 oneOf。
    2. 看 generator importMode 是否 preserve。
    3. 看用户是否设置 publicPath。
    4. 看 CSS extract 是否保留相对路径。
    5. 看 SVGR patch 是否替换了 runtime publicPath。

    资源问题通常不是 TypeScript 层能发现的，必须检查输出内容。

    修改 dts 接入的步骤

    Core 侧 dts 改动要确认：

    • dts === true 的默认值是否仍是 bundleless。
    • dts.autoExtension 是否跟 format 一致。
    • autoExternal 是否传入插件。
    • banner.dts 和 footer.dts 是否传入插件。
    • redirect.dts 是否传入插件。
    • 多 environment 是否会互相清理输出。

    如果改动涉及 plugin-dts 后端，还要到 packages/plugin-dts 增加对应测试。Core integration 负责验证 Rslib 用户配置到产物的完整链路。

    修改 CLI 的步骤

    新增 CLI 参数时：

    1. 在 commands.ts 定义 option。
    2. 更新对应 options 类型。
    3. 在 applyCliOptions 中覆盖配置。
    4. 如果参数影响配置加载，放到 CommonOptions 并在 init 中处理。
    5. 更新 help 文案测试或 CLI integration。

    不要在 action 回调里直接拼 Rsbuild 配置。那样会绕过 createRslib，导致 API 和 CLI 行为不一致。

    修改错误信息

    Core 错误信息面向用户，不只是开发者。好的错误信息应包含：

    • 哪个配置字段有问题。
    • 收到了什么值。
    • 为什么不支持。
    • 用户应该怎么改。
    • 如有必要，给文档链接。

    错误信息不要过度依赖底层 Rspack 栈。Rslib 应在能提前判断的地方提前报错，比如 bundle 模式禁止 glob entry、UMD/IIFE 禁止 bundleless、exe 禁止多 entry。

    Inspect 是排障入口

    很多问题应先让用户运行 rslib inspect。维护者自己也应使用 inspect 对照：

    • Rslib 原始配置。
    • Rsbuild environment 配置。
    • Rspack bundler config。
    • externals 顺序。
    • output filename。
    • plugins 列表。

    如果一个新能力无法在 inspect 中看出最终配置，大概率后续排障会困难。

    推荐测试组合

    改动最小测试
    format 输出对应 format integration 加产物断言
    externalexternals、auto-external、bundleless external false
    bundleless pathredirect、bundle-false、outBase
    CSSstyle redirect、CSS Modules、Vue 或 React component
    assetasset、SVGR 相关 case
    dtsplugin-dts unit 加 Rslib dts integration
    CLIcore CLI unit 加 runCliSync integration
    exeintegration-exe

    如果时间有限，优先跑最接近改动的 integration case，而不是全量测试。全量测试适合最终合并前。

    常见症状到源码入口

    症状先看
    CLI 参数无效src/cli/commands.ts、src/cli/init.ts
    找不到 configsrc/loadConfig.ts
    --lib 找不到目标composeRsbuildEnvironments、pruneEnvironments
    ESM import external 异常composeExternalsWarnConfig、composeExternalsConfig
    bundleless import 路径错误composeBundlelessExternalConfig
    CSS Modules 输出异常cssExternalHandler、libCssExtractLoader
    资源 publicPath 异常assetConfig.ts、LibSvgrPatchPlugin.ts
    dts 扩展名不对composeOutputFilenameConfig、composeDtsConfig
    exe 没生成composeExeConfig、ExePlugin
    watch 不重启restart.ts、_privateMeta.envFilePaths

    文档同步

    Core 改动通常要同步四处：

    1. 类型注释：packages/core/src/types/config.ts。
    2. 用户文档：website/docs。
    3. 维护文档：wiki/03-core/guides。
    4. 测试 fixture 或 README 示例。

    如果改动只是内部 bugfix，不一定需要用户文档，但维护文档应在行为规则变化时更新。