#mergeRslibConfig、inspect 与 debug 配置

#配置合并不是普通对象合并

Rslib 配置里最特殊的是 lib 数组。普通 deep merge 对数组通常只能覆盖或拼接，但 Rslib 需要更精确的语义：

• 有 id 的 lib item 按 id 合并。
• 没有 id 的 lib item 追加。
• 有 id 的 item 顺序按第一次出现保留。
• 非 lib 字段走 Rsbuild 的 mergeRsbuildConfig。

这个逻辑在 mergeRslibConfig。

#为什么按 id 合并

用户可能有基础配置和环境配置：

const base = {
  lib: [{ id: 'esm', format: 'esm' }],
};

const prod = {
  lib: [{ id: 'esm', output: { minify: true } }],
};

期望结果是同一个 esm lib item 被合并，而不是生成两个 esm 构建目标。

没有 id 的 item 无法判断是否同一个目标，因此只能追加。

#修改风险

改 mergeRslibConfig 会影响用户组合配置方式。风险包括：

• 重复构建目标。
• id 顺序变化。
• 用户覆盖失效。
• lib item 被错误合并。

这类问题可能不在普通 build 测试中暴露，需要专门测 mergeConfig。

#inspect 的价值

rslib inspect 是排查配置派生问题的首选工具。它能输出：

• Rslib 原始配置。
• Rsbuild config。
• Rspack bundler config。

对于以下问题，inspect 比读源码更直接：

• externals 顺序。
• output filename。
• environment id。
• plugins 列表。
• target。
• minify。
• Rspack output。

#debug inspect plugin

createRslib.ts 中有 applyDebugInspectConfigPlugin。当 debug key 包含 rslib 时，它会在首次 build 或 dev server 后写出 inspect config。

这适合排查“构建过程中最终 config 到底是什么”的问题，尤其是用户配置函数、env、CLI 覆盖、多 environment 同时存在时。

#inspect 和源码文档的关系

文档解释规则，inspect 验证实例。

如果用户说“为什么我的 external 不对”，不要只讲规则。应该让他看 inspect 中：

• environment 名称。
• output.externals。
• tools.rspack.externalsType。
• output.filename。
• source.entry。

这样能区分是用户配置没生效，还是 Rslib 派生逻辑有 bug。

#维护建议

新增配置项时，如果它会影响最终 Rspack config，应确认 inspect 能看到结果。否则用户排障会很困难。

新增多 environment 行为时，应确认 inspect 输出能区分每个 environment。

修改 debug inspect 行为时，注意不要在普通模式写磁盘，也不要破坏 cleanOutput 插件顺序。