Renovate 的 Nix Flake 依赖更新支持：flake.lock 与 flake.nix 的自动化维护指南-平芜编程栈

Renovate 的 Nix Flake 依赖更新支持：flake.lock 与 flake.nix 的自动化维护指南

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate

本篇技术指南以 Renovate 仓库中 lib/modules/manager/nix/readme.md 为骨架，系统讲解 Renovate 对 Nix Flake 依赖的自动化更新能力：包括flake.lock的lockFileMaintenance刷新与 input 更新两种模式、depName与packageName的字段语义、受支持的输入类型与更新边界，以及配套的底层命令调用与版本策略。读完本文，你将能够在自己的 Nix Flake 仓库中正确启用并配置 Renovate，让 nixpkgs 及其它 flake inputs 的升级由机器人自动完成。

一、Nix manager 支持的能力总览

Renovate 通过lib/modules/manager/nix/目录下的 manager 实现对 Nix Flake 项目的依赖管理。按照官方文档（lib/modules/manager/nix/readme.md）的定义，该 manager 支持两类更新：

lockFileMaintenance更新：针对flake.lock的常规维护式刷新，即不指定具体 input，一次性更新锁文件中所有可更新的输入；
input 更新：针对flake.lock中某个具体 flake input（例如nixpkgs）的定向升级，此时只会更新被指定的输入。

从 manager 的声明式配置（lib/modules/manager/nix/index.ts）可以确认以下关键能力标记：

配置项	值	含义
`supportsLockFileMaintenance`	`true`	声明支持 lock file 维护
`lockFileNames`	`['flake.lock']`	唯一需要维护的锁文件
`lockFileMaintenanceIsDelegatedToPackageManager`	`true`	锁文件维护交由`nix`命令本身完成（即`nix flake update`），而非 Renovate 自行改写文件
`managerFilePatterns`	`['/(^\|/)flake\\.nix$/']`	仅在名为`flake.nix`的文件上触发该 manager
`enabled`	`false`	默认关闭，需要用户显式启用
`supportedDatasources`	`git-refs`	所有 input 统一使用 GitRefsDatasource 解析新版本

其中enabled: false意味着：在默认的 Renovate 配置下，即使仓库中存在flake.nix，Nix 依赖更新也不会自动执行，必须在renovate.json中显式打开该 manager，见下文第五节。

二、理解 depName 与 packageName：写对 packageRules 的前提

在配置packageRules之前，必须先搞清楚 Nix 更新场景下 Renovate 如何命名依赖。文档（lib/modules/manager/nix/readme.md）给出了两条精确规则：

depName等于 Nix flake input 的名称。例如对于声明：
```
nix.inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
```
其depName就是nixpkgs，与flake.nix中inputs.nixpkgs的键名一一对应；
packageName等于包来源的完全限定根 URL。以上述为例，packageName为https://github.com/NixOS/nixpkgs。

这一语义在提取器实现（lib/modules/manager/nix/extract.ts）中有更完整的体现，不同锁定类型的packageName构造规则如下：

locked 类型	`packageName`构造方式	代码位置
`github`（普通仓库）	`https://<host 或 github.com>/<owner>/<repo>`	extract.ts
`github`（NixOS/nixpkgs 特例）	固定为`https://github.com/NixOS/nixpkgs`，并使用`nixpkgs`版本策略	extract.ts
`gitlab`	`https://<host 或 gitlab.com>/<owner 经 decodeURIComponent>/<repo>`	extract.ts
`git`	直接使用`original.url`	extract.ts
`sourcehut`	`https://<host 或 git.sr.ht>/<owner>/<repo>`	extract.ts
`tarball`（可锁定的 channel URL）	固定为`https://github.com/NixOS/nixpkgs`，`currentValue`取 channel 名	extract.ts
`tarball`（普通 HTTP tar 包）	从`.../archive/<rev>.tar.gz`形式的 URL 反推为`https://<domain>/<owner>/<repo>`	extract.ts

因此，一条典型的packageRules可以这样写：

{ "packageRules": [ { "matchManagers": ["nix"], "matchDatasources": ["git-refs"], "matchPackageNames": ["https://github.com/NixOS/nixpkgs"], "groupName": "nixpkgs" } ] }

依据上述语义，规则将精确命中所有根 URL 指向 NixOS/nixpkgs 的 input（包括以 channel tarball 形式锁定的 nixpkgs），而不会误伤其它 GitHub 仓库来源的 input。

三、提取逻辑：Renovate 如何解析 flake.nix 与 flake.lock

3.1 工作流程

提取入口extractPackageFile（lib/modules/manager/nix/extract.ts）的处理链路如下：

通过getSiblingFileName(packageFile, 'flake.lock')定位与flake.nix同目录的flake.lock；
读取并解析flake.lock：先用 schema.ts 中定义的 Zod schema 做安全解析（NixFlakeLock.safeParse），要求version必须为字面量7，且nodes中的每个节点可包含inputs、locked、original三部分；
取出nodes.root.inputs（根 flake 的直接 inputs），仅对这些直接输入建立依赖；
对每个直接 input，结合locked（锁定的具体版本信息）与original（声明时的原始信息）两条记录构造PackageDependency。

3.2 哪些 input 会被跳过

从源码（lib/modules/manager/nix/extract.ts）可以总结出明确的跳过规则：

root节点本身（它是魔法入口，只引用其它 inputs）；
非root.inputs中的节点，即传递性/间接依赖（skip all locked and transitive nodes as they cannot be updated by regular means）；
original或locked类型为indirect的 input——因为它依赖 flake registry 的解析结果，无法可靠更新；
original或locked类型为path的 input——本地路径无法远程升级；
locked中没有rev字段的 input——没有可追踪的提交哈希，无法更新。

这些规则在 extract.spec.ts 中有对应的单元测试覆盖，例如returns null when original inputs are from local path、returns null when locked inputs are indirect等用例。

3.3 锁定版本与摘要的表示方式

对于保留在依赖列表中的 input（extract.ts）：

若original中声明了rev（即用户在flake.nix里以 commit hash 固定了该 input），则生成currentValue = original.ref、currentDigest = original.rev、replaceString = original.rev，表示该依赖以摘要形式锁定，可直接升级；
否则只生成lockedVersion = locked.rev，把实际版本写入锁文件，等待 lock file maintenance 期间统一刷新。

另外还有一个值得注意的细节：如果flake.nix中的 URL 已经包含新的 digest（例如用户手动改了 hash），而锁文件仍记录旧 hash，提取器会根据config.currentDigest/config.newDigest把original.rev覆盖为新值（extract.ts），从而保证后续校验通过。

3.4 nixpkgs 的特殊版本策略

所有 input 默认使用git版本策略（versioning: git）并基于git-refsdatasource。但对于指向 NixOS/nixpkgs 的 input，会改用独立的nixpkgs 版本策略（versioning: nixpkgs，见 extract.ts）。该版本策略的定义位于 lib/modules/versioning/nixpkgs/readme.md：

NixOS 发行版遵循YY.MM模式（如22.05），并允许前缀/后缀组合：release-22.05、nixos-22.05、nixos-22.05-small、nixos-22.05-aarch64、nixpkgs-22.05-darwin；
还存在浮动版本：nixos-unstable、nixos-unstable-small、nixpkgs-unstable。

这意味着对nixpkgs这类 input，Renovate 能正确比较nixos-unstable与nixos-24.05等不同形态的版本，避免将其误当作普通 git 引用处理。

四、更新与制品生成：底层执行的 nix 命令

4.1 命令构造

当 Renovate 决定更新后，会调用updateArtifacts（lib/modules/manager/nix/artifacts.ts）来重新生成flake.lock。其核心逻辑是执行真正的nixCLI：

nix --extra-experimental-features 'nix-command flakes' flake update <input1> <input2> ...

input 更新模式：flake update后追加本次更新的依赖名（depName列表，经shlex.quote转义）；
lockFileMaintenance 模式：直接执行nix flake update（不带任何 input 参数），一次性刷新全部输入——这正是 index.ts 中lockFileMaintenanceIsDelegatedToPackageManager = true的含义，锁文件的维护工作完全交给 Nix 自身完成。

--extra-experimental-features 'nix-command flakes'是启用 Nix 命令与 flake 功能所必需的实验特性开关。如果检测到可用的 GitHub token（通过 hostRules 查找github.com），命令还会附加：

--extra-access-tokens github.com=<token>

以便在访问私有或受限的 GitHub 源时完成鉴权。

4.2 运行环境与错误处理

执行上下文（artifacts.ts）声明了toolConstraints中的nix工具及其版本约束（来自配置的constraints.nix）。这意味着 Renovate 会根据运行环境自动选择合适的执行方式：

binarySource=global：直接调用宿主机的nix；
binarySource=docker/install：通过 sidecar 容器或install-tool安装指定版本的 Nix 后再执行。

命令执行后，Renovate 通过getRepoStatus()检查工作区中flake.lock是否确实被修改：有修改才生成addition类型的制品文件并附带到 PR 中；没有修改则返回null；命令失败则返回包含artifactError的结果（fileName与stderr）。这些行为在 artifacts.spec.ts 中均有测试验证，例如returns null if unchanged、adds GitHub token、supports docker mode、catches errors等。

4.3 版本策略的选择

getRangeStrategy（lib/modules/manager/nix/range.ts）决定了 Range 策略：

当依赖已有currentValue（即在flake.nix中显式声明了 ref，如分支名或版本号）时，返回replace，直接替换该值；
否则返回update-lockfile，即只更新锁文件而不触碰flake.nix。

这正好与 3.3 节的字段生成逻辑相呼应：显式 ref 走“替换声明”路线，纯锁定 input 走“锁文件更新”路线。对应测试见 range.spec.ts。

五、在你的仓库中启用 Nix 依赖更新

由于 Nix manager 默认enabled: false（index.ts），需要显式开启。最小配置示例（renovate.json）：

{ "nix": { "enabled": true } }

5.1 启用 lockFileMaintenance

如需定期刷新整个flake.lock，请同时打开lockFileMaintenance（参考 docs/usage/configuration-options.md 的通用说明）：

{ "nix": { "enabled": true }, "lockFileMaintenance": { "enabled": true } }

说明：

lockFileMaintenance默认也是关闭的；
开启后，Renovate 会按既定调度（默认"before 4am on monday"，即每周一次）运行nix flake update刷新flake.lock；
由于本 manager 将锁文件维护委托给了 Nix（lockFileMaintenanceIsDelegatedToPackageManager），执行的是真实nix命令，因此要求运行环境（容器或宿主）具备可用的 Nix 工具链，或已配置constraints.nix让 Renovate 自动安装对应版本。

5.2 配合 packageRules 精细化控制

结合第二节的depName/packageName语义，可以精确控制某一类 input 的更新行为，例如让所有指向 NixOS/nixpkgs 的 input 每周只更新一次：

{ "nix": { "enabled": true }, "packageRules": [ { "matchManagers": ["nix"], "matchPackageNames": ["https://github.com/NixOS/nixpkgs"], "schedule": ["before 6am on monday"] } ] }

5.3 适用前提与限制

仓库必须同时包含flake.nix与同目录的flake.lock，且flake.lock的version为 7；
只有root 的直接 inputs才会被跟踪更新，传递性（transitive）inputs 会被跳过；
indirect与path类型的 input 无法被 Renovate 更新；
没有跟踪rev的 input 只能通过lockFileMaintenance整体刷新；
更新依赖的 Git 源时，Renovate 使用git-refsdatasource 查询远端引用，因此保证运行环境能访问对应 Git 主机（必要时配置 hostRules token）是成功生成 PR 的前提。

六、小结与源码导航

Renovate 的 Nix manager 以“flakes 原生命令驱动”为设计核心：解析阶段只关注flake.nix同目录的flake.lock，把 root 直接 inputs 映射为depName（input 名）+packageName（根 URL）；更新阶段则委托nix flake update生成新锁文件，并依据是否声明rev决定走replace还是update-lockfile策略。nixpkgs 类 input 额外获得专用的 nixpkgs 版本策略，可正确理解YY.MM与 unstable 浮动版本。

进一步阅读源码的入口：