Renovate 配置完全指南配置文件、环境变量与 CLI 参数的覆盖机制【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovateRenovate 是 Mend.io 开源的跨平台依赖自动化工具其全部行为都由一套分层配置系统驱动。本文以 docs/development/configuration.md 为骨架结合仓库源码lib/config 与 lib/workers/global/config深入讲解 Renovate 全局配置的四种注入方式、它们之间的优先级关系、配置文件格式与解析规则以及仓库级配置renovate.json、package.json的用法帮助你理解并掌握 Renovate 自托管与仓库配置的完整体系。配置的四种注入方法及其优先级Renovate 的全局self-hosted配置可以通过以下四种途径定义配置文件Configuration file附加配置文件Additional configuration file环境变量Environment variablesCLI 参数CLI parameters这四者按照优先级从低到高排列即排在后面的会覆盖前面的同名配置。文档原文特别强调上述列表是按偏好的反序排列的例如当 CLI 参数与环境变量冲突时CLI 参数生效。这一优先级规则在源码中有直接印证。在 lib/workers/global/config/parse/index.ts 的parseConfigs函数中配置的合并顺序为const defaultConfig defaultsParser.getConfig(); // 默认配置 const fileConfig await fileParser.getConfig(env); // 配置文件 const additionalFileConfig await additionalConfigFileParser.getConfig(env); // 附加配置文件 const cliConfig cliParser.getConfig(argv); // CLI 参数 const envConfig await envParser.getConfig(env); // 环境变量 let config: AllConfig mergeChildConfig(fileConfig, additionalFileConfig); config mergeChildConfig(config, envConfig); // 环境变量覆盖附加配置文件 config mergeChildConfig(config, cliConfig); // CLI 参数覆盖环境变量 config mergeChildConfig(defaultConfig, config); // 最终叠加到默认配置之上可以看出默认配置是所有配置的基底随后依次叠加配置文件、附加配置文件、环境变量和 CLI 参数——后者的值会逐层覆盖前者与文档声明的“CLI 环境变量 附加配置文件 配置文件 默认值”完全一致。值得注意的是合并过程中还会处理globalExtends全局预设并支持forceCli强制 CLI 覆盖等高级行为parse/index.ts。默认配置Renovate 的默认配置值定义在 lib/config/options/index.ts约 3700 行的完整选项清单。其中标注了globalOnly: true的选项只能用于全局自托管配置禁止出现在仓库级配置文件如renovate.json中。例如allowedHeaders、allowedEnv、autodiscoverRepoSort、binarySource、dryRun、platform、onboarding、requireConfig等都属于全局专属选项lib/config/options/index.ts 中可见allowedHeaders的定义。运行时这些选项由 lib/config/global.ts 中的GlobalConfig类统一管理——GlobalConfig.OPTIONS静态常量列出了全部全局选项名set()会从普通配置中剥离这些字段并存入全局单例仓库级处理流程便无法再改动它们。配置文件Configuration File如果不做任何设置Renovate 会在工作目录下查找名为config.js的默认配置文件。需要更换文件位置或文件名时通过环境变量RENOVATE_CONFIG_FILE指定例如RENOVATE_CONFIG_FILE/etc/renovate/myconfig.js源码中这一逻辑位于 lib/workers/global/config/parse/file.tsconst configFile env.RENOVATE_CONFIG_FILE ?? config.js。若显式设置了RENOVATE_CONFIG_FILE但文件不存在Renovate 会直接process.exit(1)报错退出而不会静默忽略。附加配置文件Additional Configuration File除了主配置文件你还可以指定第二份配置文件它会在主配置文件之后加载并覆盖其同名配置常用于分层管理例如把基础设置与敏感环境相关设置拆开。附加配置文件没有默认文件名必须通过环境变量RENOVATE_ADDITIONAL_CONFIG_FILE显式指定RENOVATE_ADDITIONAL_CONFIG_FILE/etc/renovate/additional.json对应实现在 lib/workers/global/config/parse/additional-config-file.ts同样遵循“文件必须存在否则 fatal 退出”的规则。两份配置文件的extends数组会被合并处理parse/index.ts。文件扩展名与格式要求注意RENOVATE_CONFIG_FILE和RENOVATE_ADDITIONAL_CONFIG_FILE都必须携带明确的文件扩展名。例如写成RENOVATE_CONFIG_FILEmyconfig.js或RENOVATE_CONFIG_FILEmyconfig.json而不是RENOVATE_CONFIG_FILEmyconfig。如果未提供扩展名或文件类型不受支持Renovate 将启动失败。如果你所在的仓库是 ESM 仓库package.json中声明了type: module那么配置文件必须使用.cjs扩展名并设置RENOVATE_CONFIG_FILE例如RENOVATE_CONFIG_FILEmyconfig.cjs。从源码 lib/workers/global/config/parse/util.ts 的getParsedContent可以看出当前版本实际支持的配置文件格式包括扩展名解析方式.js/.cjs/.mjs/.ts/.cts/.mts优先按 ESMimport加载.js/.ts失败时回退为 CommonJSrequire也支持导出为函数的配置.json/.jsonc/.json5按 JSON/JSONC/JSON5 解析.yaml/.yml按 YAML 解析.renovaterc特殊文件名按 JSON 解析此外仓库中还保留了 lib/config/parse.ts 的parseFileConfig逻辑它对 JSON 会先剥离注释JSONC、容忍尾逗号并通过json-dup-key-validator做重复键检查重复键会直接报 “Duplicate keys in JSON” 错误——这也是仓库配置解析环节的严谨性所在。配置文件示例与粒度控制使用配置文件可以获得非常细粒度的配置能力大多数设置都可以在全局文件级、仓库级或包级分别覆盖。例如可以在同一个仓库内为backend/package.json应用一组标签、为frontend/package.json应用另一组标签。原文档给出的配置文件示例module.exports { npmrc: //registry.npmjs.org/:_authTokenabc123, baseDir: /tmp/renovate, forkProcessing: enabled, gradle: { enabled: false }, };结合当前仓库的选项定义lib/config/options/index.ts这些字段的含义如下npmrc向 npm 客户端注入的.npmrc内容用于私有源认证此处示例直接内嵌了 registry 的 auth tokenbaseDirRenovate 的工作基目录默认值见选项定义用于控制缓存与 git 克隆目录位置forkProcessing控制 fork 仓库的处理方式取值可为enabled/disabled/auto自托管场景默认会随autodiscover状态被自动调整parse/index.tsgradle: { enabled: false }演示了按 manager 维度关闭某个依赖管理器manager 的enabled选项在仓库中广泛使用。更细粒度的包级覆盖通常通过packageRules实现其定义位于 lib/config/options/index.ts例如module.exports { packageRules: [ { matchFileNames: [backend/package.json], labels: [backend-update], }, { matchFileNames: [frontend/package.json], labels: [frontend-update], }, ], };CLI 参数Renovate 也支持通过命令行直接传参。首先可以查看完整帮助node renovate --helpCLI 参数与配置选项一一对应且优先级最高。对于list类型的列表选项使用逗号分隔多个值例如renovate --labelsrenovate,dependency如需开启调试日志可向环境导出LOG_LEVELdebugexport LOG_LEVELdebugCLI 配置的解析实现在cliParser.getConfig(argv)parse/index.ts其内部会将--xxxyyy形式的参数转换为配置对象。源码中还保留了一个细节如果 CLI 通过--repositories覆盖了配置文件或环境变量中已设置的repositoriesRenovate 会打印警告日志parse/index.ts提醒你注意覆盖行为。仓库级配置renovate.json除了全局配置你还可以在仓库根目录添加renovate.json文件来覆盖默认设置。这是最常用的仓库级配置入口内容采用 JSON/JSON5/JSONC 格式例如本仓库根目录就存在一个 renovate.json。仓库级配置文件的名字不是写死的全局选项configFileNames允许自定义仓库配置文件名的列表lib/config/options/index.tsonboardingConfigFileName则控制 onboarding PR 中生成的文件名默认renovate.json见 lib/config/options/index.ts。在自托管场景中这些列表会在配置解析时被写入全局配置并作用于所有仓库parse/index.ts。需要再次强调globalOnly: true的选项如platform、binarySource、dryRun等不能出现在renovate.json中否则校验会报错。仓库级配置package.json如果你在仓库的package.json中添加renovate字段它会覆盖上述所有其他设置此处指的是在仓库级配置源中拥有最高优先级——实际运行时的完整覆盖顺序仍以“仓库配置 → 平台/默认”的合并链路为准。原文档示例{ renovate: { labels: [upgrade, bot] } }这段配置表示对当前仓库的所有依赖更新 PR 打上upgrade与bot两个标签。package.json中的renovate字段与renovate.json等效两者任选其一即可同时存在时行为见 Renovate 仓库配置合并逻辑.renovaterc也是同级的备选文件名源码在 lib/workers/global/config/parse/util.ts 中做了特殊处理。配置合并的底层原理理解了入口之后再看 Renovate 是如何把多层配置合成一份的。核心函数是 lib/config/utils.ts 的mergeChildConfig采用浅拷贝叠加子配置逐键覆盖父配置对标记了mergeable: true的选项做特殊合并数组类型会拼接concat而不是整体替换对象类型会递归合并constraints等对象选项按键合并合并结果的最后会叠加config.force强制覆盖段保证force语义始终最高合并前会通过clone()做深拷贝避免对原始配置对象的意外修改。此外每份配置文件在进入合并前都会经过migrateAndValidateConfiglib/workers/global/config/parse/util.ts这条流水线migrate若配置中存在已废弃的选项名或格式自动迁移到新格式并打印 “Config needs migrating” 警告迁移逻辑见 lib/config/migration.ts 与 lib/config/migrationsmassage剔除无效字段、规范化类型lib/config/massage.tsvalidate按全局/仓库两级做校验输出 warnings 与 errorslib/config/validation.ts。也就是说即使配置文件里写了过时的写法Renovate 也会尽力迁移而不是直接拒绝这大大降低了配置维护成本。全局专属选项速览所有用户可配置选项的权威清单就是 lib/config/options/index.ts每个选项都带有name、description、type、default等元信息。其中全局专属globalOnly: true的选项从 lib/config/global.ts 的GlobalConfig.OPTIONS常量可以确认常见包括平台与仓库发现platform、autodiscoverRepoOrder、autodiscoverRepoSort、endpoint、configFileNames、onboarding*系列安全与权限allowedCommands、allowedEnv、allowedHeaders、allowPlugins、allowScripts、internalHostAccess、exposeAllEnv运行行为binarySource、cacheDir、dryRun、executionTimeout、gitTimeout、userAgent、requireConfig、migratePresets、customEnvVariables缓存与网络httpCacheTtlDays、cacheHardTtlMinutes、cachePrivatePackages、mergeConfidenceEndpoint、mergeConfidenceDatasources、s3Endpoint、s3PathStyle。这些选项的典型用法自托管配置示例可进一步参考 docs/usage/self-hosted-configuration.md面向用户的所有配置选项说明见 docs/usage/configuration-options.md。小结Renovate 的配置体系可以概括为一张分层覆盖表配置来源注入方式优先级默认配置lib/config/options/index.ts 中的default最低基底配置文件工作目录config.js或RENOVATE_CONFIG_FILE指定低附加配置文件RENOVATE_ADDITIONAL_CONFIG_FILE指定中环境变量RENOVATE_*系列高CLI 参数node renovate --xxxyyy最高仓库级配置renovate.json/package.json的renovate字段则是在全局配置之上针对单个仓库/包做进一步的细粒度覆盖其中globalOnly: true的选项只能在全局层出现。理解这套机制你就能精准预测“哪个配置最终生效”并利用LOG_LEVELdebug观察配置解析过程中的每一层合并结果快速定位配置问题。【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
