Rolldown CLI 实现解析基于 cac 的参数解析流水线与设计细节【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown本文以 Rolldown 仓库内部设计文档 internal-docs/cli/implementation.md 为主线结合 packages/rolldown/src/cli 目录下的真实源码与 CLI 端到端测试完整还原 Rolldown CLI 的参数解析架构。读完本文你将掌握Rolldown CLI 如何借助 cac 完成选项注册与解析、如何通过一层后处理流水线解决未知选项、原型污染、对象选项、短别名去重等问题以及 input/output 选项如何被拆分并最终驱动打包流程。一、CLI 设计总览为什么选择 cacRolldown CLI 的参数解析库是 cac 中体现为三点kebab-case 与 camelCase 可互换匹配cac 内部通过camelcaseOptionName处理转换选项以 camelCase 键注册但命令行中--moduleTypes与--module-types均可命中修复了 issue #8410required与[optional]值语义required强制要求携带值[optional]允许省略值并返回true修复了-s inline的位置限制问题issue #3248点号嵌套与数组自动累积--transform.define XY可自动转为嵌套对象重复标志可自动累积为数组。二、完整解析流水线internal-docs/cli/implementation.md 给出了从进程入口到真正执行打包的完整调用链bin/cli.mjs → src/cli/index.ts (entry) → checkNodeVersion() → parseCliArguments() → arguments/index.ts → getCliSchemaInfo() — 将 valibot schema 扁平化为 { key: { type, description } } → build options export — 供 help.ts 使用camelCase 键与 Rollup/Vite 帮助展示对齐 → build knownKeys / shortAliases — 供后处理使用 → register options with cac — 遍历 schemaInfo alias构造 rawName 字符串 → cli.parse(process.argv, { run: true }) → post-processing: → 删除 -- 键与短别名重复项 → 原型污染防护 → 未知选项检测 警告 → rawArgs 快照 → 删除未知键 → 类型强制转换去重 数组包装 → 对象选项解析 (key:val,key:val) → arguments/normalize.ts → validateCliOptions() 经 valibot 校验 → 按 schema 键拆分 input/output → 将位置参数合并进 input.input → 处理 --environment (KEY:VALUE → process.env) → 若 --help: showHelp() → 若 --version: 打印版本 → 若 --config: bundleWithConfig(configPath, cliOptions, rawArgs) → 若指定 input: bundleWithCliOptions(cliOptions) → 否则: showHelp()流水线的入口在 packages/rolldown/src/cli/index.ts启动时先调用checkNodeVersion(process.versions.node)检查 Node 版本源码中明确提示Rolldown requires Node.js version 20.19 or 22.12不满足时仅告警、不阻止运行。随后main()按help → version → config → input → help的优先级依次分流--help拥有最高优先级对应 issue #8523rolldown lib -o dist/lib.js --help也应展示帮助其次是版本号、配置文件、命令行输入最后兜底展示帮助。三、关键文件地图internal-docs/cli/implementation.md 中的文件职责表结合源码可对应到仓库内的真实位置文件仓库相对路径职责packages/rolldown/src/cli/index.ts入口——编排整条流水线处理--environment、分流 help/version/config/inputpackages/rolldown/src/cli/arguments/index.ts核心解析——cac 初始化、选项注册、完整后处理流水线packages/rolldown/src/cli/arguments/normalize.ts将扁平选项拆分为input/output用 valibot 校验packages/rolldown/src/cli/arguments/alias.ts短标志、reverse、requireValue、hint配置packages/rolldown/src/cli/arguments/utils.tssetNestedProperty、camelCaseToKebabCase工具函数packages/rolldown/src/cli/commands/help.ts自定义帮助文本生成读取options导出packages/rolldown/src/cli/commands/bundle.tsbundleWithConfig、bundleWithCliOptions、watch 模式packages/rolldown/src/cli/logger.tsconsola 日志器ROLLDOWN_TEST1时替换为裸console.logpackages/rolldown/src/utils/validator.ts所有 CLI 选项的 valibot schema、getCliSchemaInfo()、input/output 键列表packages/rolldown/src/utils/flatten-valibot-schema.ts递归扁平化 valibot 对象 schema 为{ key: { type, description } }四、parseCliArguments()的返回结构解析函数返回的是已归一化的选项对象外加一份原始参数快照interface NormalizedCliOptions { input: InputOptions; output: OutputOptions; help: boolean; config: string; version: boolean; watch: boolean; environment?: string | string[]; } // 另外附带 rawArgs: Recordstring, any —— 全部已解析参数含未知项normalize.ts 中的实际定义还额外包含configLoader?: ConfigLoader对应--configLoader选项。源码中用reservedKeys new Set([help, version, config, watch, environment, configLoader])区分保留键与真正的打包选项凡不落在 input/output 键列表又不属于保留键的键都会以Unknown option: xxx报错退出。位置参数positionals在最后合并rolldown 1.ts --input ./2.js等价于将1.ts追加到input.input数组。五、cac 选项注册机制选项注册循环schemaInfo 由 valibot schema 扁平化而来键为 camelCase如moduleTypes。注册时直接以 camelCase 键构造 rawNamecac 会自动兼容 kebab 写法for (const [key, info] of Object.entries(schemaInfo)) { const config alias[key as keyof typeof alias]; let rawName ; if (config?.abbreviation) rawName -${config.abbreviation}, ; if (config?.reverse) { rawName --no-${key}; } else { rawName --${key}; } // 括号语法决定 cac 的处理方式 // - 无括号 → 布尔注册进 mri 的 boolean 列表 // - required → 字符串缺值抛 CACError // - [optional] → 字符串无值跟随则返回 true if (info.type ! boolean !config?.reverse) { if (config?.requireValue) { rawName ${config?.hint ?? key}; } else { rawName [${config?.hint ?? key}]; } } cli.option(rawName, info.description ?? config?.description ?? ); }这段代码与 arguments/index.ts 完全一致。三种括号语义决定了选项的取值行为是理解 CLI 各种边界行为尤其--sourcemap的双重行为的根基。默认命令const cmd cli.command([...input], ); cmd.allowUnknownOptions(); // 关闭 cac 的未知选项报错——由我们自己告警 cmd.ignoreOptionDefaultValue(); // 阻止 cac 注入 --no-* 的默认值 cmd.action((input, opts) { ... }); cli.parse(process.argv, { run: true });两个方法都至关重要allowUnknownOptions()把未知选项的处理权收归己有cac 不再抛错后续由后处理阶段统一检测并输出格式一致的警告ignoreOptionDefaultValue()禁用 cac 为--no-*选项自动注入的default: true。以preserveEntrySignatures为例它只接受falsecac 注入的true会直接破坏 valibot 校验禁用后选项保持undefined由 bundler 内部自行应用默认值ExportsOnly。六、cac 提供的能力 vs Rolldown 自研能力文档对两者边界划分得很清晰源码也逐一印证cac底层 mri直接提供的能力camelCase/kebab-case 互换匹配修复 #8410--no-*布尔取反required值校验——checkOptionValue()抛CACError[optional]值解析——修复-s inline位置限制#3248点号嵌套setDotProp--transform.define XY→{ transform: { define: XY } }短标志别名与堆叠-ms--minify --sourcemap重复标志自动累积为数组。Rolldown 自己实现的部分对象选项解析——--module-types .atext,.bjson先按,分段再按分隔符拆分支持逗号分隔单次传入与重复标志两种写法未知选项告警——allowUnknownOptions()抑制 cac 报错由己方检测并以自有消息格式告警原型污染防护——cac 的setDotProp不防护__proto__、constructor、prototype需要手动清洗input/output 拆分——normalize.ts 中把扁平选项拆成InputOptions与OutputOptions自定义帮助文本——不用cli.help()而是自写生成器带排序、对齐、示例与备注重复选项去重——非数组类型取最后一个值external与input保留数组rawArgs 组装——解析结果含未知项的快照用于透传给配置函数短别名键清理——mri 会同时产出短名与长名两个键如{ s: true, sourcemap: true }需删除短键。此外 arguments/index.ts 中还有一个文档未展开的实现camelizeNestedKeys()会递归把嵌套键从 kebab-case 转为 camelCase——因为 cac 只转换顶层选项名--transform.define产生的{ transform: { define: ... } }若用户在嵌套层使用 kebab 键则不会被自动转换这里做了补齐。七、后处理顺序9 步流水线internal-docs/cli/implementation.md 给出的后处理顺序在 arguments/index.ts 中依次落地删除parsedOptions[--]——cac 会把--之后的参数收集到独立的--键下游无消费方直接删除删除短别名重复键——遍历启动时收集的shortAliases集合逐一删除原型污染防护——对__proto__、constructor、prototype及其带点号前缀的变体如__proto__.x全部删除未知选项检测 告警——用knownKeys含由点号 schema 键预计算的父键见下文过滤对未知键输出Option \xxx is unrecognized. We will ignore this option.rawArgs 快照——在删除未知键之前拷贝{ ...parsedOptions }保证配置函数能拿到完整原始参数从 parsedOptions 删除未知键类型强制转换——单一循环内同时完成去重与数组包装数组值且 schema 类型非 array/object 时取最后一个元素string 值但 schema 类型为 array 时包装为单元素数组对象选项解析——遍历 schema 中type object的键沿点号路径找到叶节点后解析key:val,key:val字符串normalizeCliOptions()——valibot 校验 input/output 拆分。其中对象选项解析的细节值得展开arguments/index.ts它会先按点号路径逐层下钻找到叶节点而不是只遍历顶层条目取值支持数组重复标志与单字符串两种来源对每个key:value对优先按:分隔仅当:不存在或出现在:之前时回退到分隔且回退会输出Using \keyvalue syntax for --xxx is deprecated. Use key:value instead. 的废弃告警。这意味着--module-types .atext,.bjson中.atext这类含点的键会按拆分为{ .a: text }值本身含:时如keyvalue:with:colon的旧写法分支的pair.slice(eqIdx 1)保留全部剩余字符不会误切。八、关键实现细节CACError未被导出cac 只导出cac、CAC、Command三个符号CACError定义在 cac 内部的utils.ts中但未重新导出。Rolldown 通过err?.name CACError判断错误类型并对option \xxx value is missing格式的消息做二次解析输出更友好的Option xxx requires a value but none was provided.随后process.exit(1)。ignoreOptionDefaultValue()前文已述cac 会为所有--no-*选项注入default: true导致preserveEntrySignatures只接受false校验失败。Rolldown 完全禁用 cac 的默认值机制让 bundler 处理自身的默认值逻辑——源码注释明确写道we want it to beundefinedby default。短别名键重复mri 会把短标志和长标志同时写入结果-s→{ s: true, sourcemap: true }。启动时收集全部短别名到shortAliases集合后处理第一步就批量删除。嵌套选项的父键cac 的setDotProp把--transform.define value变成{ transform: { define: value } }。但扁平化的schemaInfo中只有transform.define、transform.target等完整键顶层transform并不存在。因此knownKeys的构建逻辑会从点号分隔的 schema 键中预计算父键key.indexOf(.) 0时截取前缀加入集合否则--transform.define会被误判为未知选项。对象选项解析的遍历方式由于 cac 已通过setDotProp生成了嵌套结构对象解析步骤沿点号路径下钻定位字符串值而非遍历顶层条目从而避免重复展开嵌套对象。--config的可选值-c注册为[optional]无值跟随如rolldown -c时 cac 返回config: true。normalize.ts 将config: true映射为config: 保留自动探测配置文件rolldown.config.mjs等的行为。--environment不是对象选项--environment使用:与,分隔Rollup 兼容在 cli/index.ts 中被单独处理按,分段、按:切分 key/value写入process.env无:的值如PRODUCTION等价于process.env.PRODUCTION true。它的 schema 类型是string | string[]与对象选项解析完全无关。--分隔符parseArgs会把--之后的参数视为位置参数cac 则将其收集到options[--]数组中。后处理第一步删除该键因为下游没有任何代码消费它。九、边界情况分析--sourcemap的双重行为-s 单独使用 → true -s inline → inline --sourcemap hidden → hidden注册为-s, --sourcemap [type]。[optional]括号使 mri不把-s当布尔它会吞掉下一个非标志参数作为值若没有值跟随则返回true。--no-preserve-entry-signatures传入时 cac 置preserveEntrySignatures: false未传入时为undefined由 bundler 应用自身默认值ExportsOnly。这正是ignoreOptionDefaultValue()生效的场景。对象选项值中含逗号--transform.define __A__A,__B__B——cac 返回单一字符串__A__A,__B__B后处理按,拆分并解析为{ __A__: A, __B__: B }。原型污染cac 的setDotProp不防护__proto__、constructor、prototypeRolldown 在归一化前删除所有此类键含带点号前缀的变体防止恶意参数污染对象原型。十、测试矩阵与运行方式CLI 的端到端测试位于 packages/rolldown/tests/cli/cli-e2e.test.ts运行命令cd packages/rolldown/tests pnpm test:cli测试基于execa以子进程方式真实执行rolldown命令并对 stdout 做两次清洗后与快照比对去除 ANSI 颜色、抹掉不确定的耗时Finished in x ms与版本号替换为rolldown VERSION)。快照存于 packages/rolldown/tests/cli/snapshots/cli-e2e.test.ts.snap。logger.ts 中ROLLDOWN_TEST1时用裸console.log替换 consola正是为了保证测试环境下日志输出可预测。文档给出了 21 个覆盖场景的测试矩阵涵盖全部关键能力#功能示例1--version/-vrolldown --version2--help/-hrolldown --help3空参数展示帮助rolldown4help 优先级#8523rolldown lib -o dist/lib.js --help5布尔选项rolldown index.ts --minify -d dist6字符串选项rolldown index.ts --format cjs -d dist7短标志rolldown index.ts -d dist -s8数组重复标志rolldown index.ts --external node:path --external node:url -d dist9对象重复标志rolldown index.ts --module-types .123text --module-types .b64base64 -d dist9a对象逗号分隔rolldown index.ts --module-types .123text,notjsonjson,.b64base64 -d dist10--no-*布尔取反rolldown index.ts --no-external-live-bindings ...11嵌套点号rolldown index.js --transform.define __DEFINE__defined12位置参数作为 inputrolldown 1.ts --input ./2.js13配置文件加载-crolldown -c rolldown.config.ts14配置函数 rawArgsrolldown -c rolldown.config.js --customArgcustomValue15CLI 覆盖配置rolldown -c rolldown.config.js --format cjs16--environmentrolldown -c --environment PRODUCTION,FOO:bar17requireValue校验rolldown 1.ts -d报错需要值18非法选项值rolldown index.ts --format INCORRECT19未知选项告警rolldown index.ts --someRandomFlag -d dist20watch 模式rolldown index.ts -d dist -w -s21camelCase 输入#8410rolldown index.ts --moduleTypes .pngdataurl -d dist测试 14 特别说明rawArgs的价值配置函数可以收到包括未知选项在内的完整原始参数。对应实现见 bundle.ts 的typeof config function ? await config(rawArgs) : config。测试 15 则由 watchInner/bundleInner 中{ ...config, ...cliOptions.input }与{ ...output, ...cliOptions.output }的展开顺序保证——CLI 选项始终覆盖配置文件。测试 20 的 watch 模式在bundleWithCliOptions中还要求必须显式提供output.dir否则报错You must specify \output.dir to use watch mode同时会设置process.env.ROLLUP_WATCH与ROLLDOWN_WATCH 以便与既有生态如 Vite 相关工具链兼容。十一、帮助文本与短标志速查help.ts 自定义生成 USAGE / OPTIONS / EXAMPLES / NOTES 四段式帮助。其中选项排序规则为优先展示带短标志的选项按短字母排序其余按长名排序string 类型选项展示hint占位符。内置示例包括rolldown -c rolldown.config.mjs rolldown src/main.ts -d dist -f cjs rolldown src/main.ts -d dist --moduleTypes .pngdataurl rolldown src/main.tsx -d dist -m -s rolldown src/main.ts -d dist -n bundle -f iife -e jQuery,window._ -g jQuery$alias.ts 中维护了完整的短标志与特殊配置表可直接查用选项短标志hint特殊配置config-cfilename可选值help-h—布尔version-v—布尔watch-w—布尔dir-d—requireValue: truefile-o—requireValue: trueexternal-e——format-f——name-n——globals-g——sourcemap-s—可选值minify-m—布尔platform-p——assetFileNames/chunkFileNames/entryFileNames—name—externalLiveBindings/treeshake/preserveEntrySignatures——reverse: true注册为--no-*moduleTypes—types—注意treeshake也注册为反向选项即--no-treeshake用于关闭摇树优化。帮助文本中对于 reverse 选项描述会自动改写为 disable ... 前缀保持语义一致。十二、附录从parseArgs到 cac 的迁移文档末尾记录了历史迁移上下文旧实现基于 Node.js 内置parseArgs并手工维护了 16 个 workaround。issue #8410 的根因正是parseArgs只认识--module-types把 camelCase 的--moduleTypes当作未知布尔丢弃到位置参数中。迁移到 cac 后变更点迁移前迁移后数字字符串强制转换--code-splitting.min-size 1000→ 字符串1000→ 数字1000mri 会转换类数字值未知选项的--no-*告警 foo is unrecognized同样告警但值为false而非缺省--分隔符之后的参数变为位置参数收集到options[--]后处理删除短标志堆叠不支持-ms--minify --sourcemap迁移还删除了alias.ts中的default字段死代码三个reverse: true选项treeshake、externalLiveBindings、preserveEntrySignatures的默认值在旧 token 循环中只对 string/union 类型生效而它们全是 boolean/reverse 类型启用ignoreOptionDefaultValue()后 cac 也从不应用默认值。十三、相关 Issue 参考#8410 — CLI 静默误处理 camelCase 选项迁移的根因#3248 —-s inline位置限制[optional]值解析的由来#8523 —--help优先级高于其他选项。这三个 Issue 共同塑造了当前 CLI 设计的三个关键决策camelCase/kebab-case 双写兼容、可选值选项的取值规则、帮助信息的优先展示。对 CLI 实现感兴趣的读者可继续阅读 cli/index.ts 与 arguments/index.ts 的完整源码以及 validator.ts 中全部 CLI 选项的 valibot schema 定义。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考