如何让Nix构建快人一步？nixos-raspberrypi二进制缓存配置完整教程-优快云博客

【免费下载链接】nixos-raspberrypi

Nix flake for a fully declarative NixOS on Raspberry Pi

项目地址： https://gitcode.com/gh_mirrors/nix/nixos-raspberrypi

在树莓派（Raspberry Pi）上用 NixOS 搭建系统，最容易踩的坑就是慢：一个 RPi 专用内核从零编译可能要等上几个小时，弱小的 CPU 更是煎熬。好消息是 nixos-raspberrypi 项目自带 nixos-raspberrypi.cachix.org 二进制缓存（binary cache），预置了内核、固件、libcamera 和 SD 卡安装镜像等成品包。只需三行配置，Nix 就能直接下载预编译产物，跳过漫长编译，让构建快人一步 ⚡

什么是 Nix 二进制缓存？为什么它是加速关键？

Nix 的包构建是确定性、可复现的——但也意味着每次换机器、换环境都可能触发重复编译。二进制缓存的原理很简单：

substituter（替代源）：Nix 构建前先查询缓存，命中就直接下载解压，不命中才本地编译；
公钥签名：缓存里的每个包都用发布者的私钥签名，Nix 下载后用公钥验签，防止被篡改。

本项目在 flake.nix 的 nixConfig 中声明了自己的缓存地址和公钥：

nixConfig = {
  extra-substituters = [
    "https://nixos-raspberrypi.cachix.org"
  ];
  extra-trusted-public-keys = [
    "nixos-raspberrypi.cachix.org-1:4iMO9LXa8BqhU+Rpg6LQKiGa2lsNh/j2oiYLNOQ5sPI="
  ];
  connect-timeout = 5;
};

💡 记住这两个值：缓存地址 https://nixos-raspberrypi.cachix.org 和 extra-trusted-public-keys 里的那串密钥，后面三种启用方式都会用到它们。

启用二进制缓存的 3 种配置方法

方法一：在 flake 的 nixConfig 中声明（构建镜像时推荐）

如果你要执行 nix build .#installerImages.rpi5 这类构建命令，把上面的 nixConfig 片段写进自己 flake 的根文件即可。这样 Nix 每次构建都会优先从缓存拉取，而不是本地编译内核。

对应官方声明位置：flake.nix。

方法二：用 lib.nixosSystem 辅助函数，默认自动启用

使用项目提供的 nixos-raspberrypi.lib.nixosSystem、nixosSystemFull 或 nixosInstaller 构建目标系统时，无需任何额外配置——trustCaches 参数默认为 true，内部会自动注入 trusted-nix-caches 模块（见 lib/internal.nix）：

nixosConfigurations.rpi5-demo = nixos-raspberrypi.lib.nixosSystem {
  # trustCaches 默认为 true，二进制缓存自动生效
  specialArgs = inputs;
  modules = [ /* 你的硬件模块，如 raspberry-pi-5.base */ ];
};

该模块做了两件关键的事（源码见 modules/trusted-nix-caches.nix）：

nix.settings.substituters：告诉 Nix 去哪里下载预编译包；
nix.settings.trusted-substituters：把缓存标记为可信，普通用户和 flake 构建也能使用，无需 root 权限。

⚠️ 这个区别很重要：只写入 substituters 的缓存在 flake 场景下默认不可用，必须同时列入 trusted-substituters，否则你会看到 "substituter not trusted" 的警告。

如果你明确不想使用缓存，只需传入 trustCaches = false。

方法三：直接导入 trusted-nix-caches 模块

当你绕过辅助函数、直接用 nixpkgs.lib.nixosSystem 组装系统时，可以从 nixosModules 里手动导入缓存模块（完整用法见 README.md 进阶用法）：

imports = with nixos-raspberrypi.nixosModules; [
  nixos-raspberrypi.lib.inject-overlays  # 内核、固件等 overlay
  trusted-nix-caches                     # 二进制缓存
];

缓存里预置了什么？内核和安装镜像都有

缓存并非空架子。构建脚本 devshells/nix-build-to-cachix.nix 完整列出了预构建并推送的包：

类别	预置包
RPi 各型号内核	`linux_rpi02` / `linux_rpi3` / `linux_rpi4` / `linux_rpi5`
固件	`raspberrypifw`、`raspberrypiWirelessFirmware`
相机栈	`libcamera`、`libpisp`、`rpicam-apps`、`raspberrypi-utils`
多媒体	`kodi-gbm`、`vlc`、`ffmpeg_8`（含 headless 版）
安装镜像	rpi02/3/4/5 四个 installer 的完整 `toplevel`

这意味着一条命令就能体验缓存的威力：

nix --accept-flake-config build .#installerImages.rpi5

--accept-flake-config 的作用就是授权 Nix 读取 flake 中声明的 nixConfig（即信任这个二进制缓存），避免自己从零编译内核。README 中也特别指出：四个 installer 镜像的 toplevel 已包含在缓存中（见 README.md）。

如何验证缓存真的生效了？

最直观的办法是观察构建日志：

执行 nix --accept-flake-config build .#packages.aarch64-linux.vlc；
如果日志里是大量 fetching / unpacking（下载解压）而非 building（gcc 编译输出），说明缓存命中；
命中缓存时，vlc 这类大包的构建通常几分钟内完成，而不是几小时。

另外，Nix 的验签机制保证了安全：如果缓存内容被篡改，构建会因签名校验失败而中止，不会静默安装来路不明的包。

常见问题：缓存没命中怎么办？

nixpkgs 版本不匹配：缓存是针对当前锁定版本的 nixpkgs 生成的（见 flake.nix 中固定的 nixos-26.05 分支）。如果你手动升级了 nixpkgs，包哈希对不上，缓存必然失效、触发本地重编译。保持与项目锁定的 nixpkgs 一致即可；
提示 substituter 不可信：确认缓存地址同时写入了 trusted-substituters（方法二的模块已自动处理），仅写入 substituters 时 flake 构建会被拒绝；
网络超时：项目默认设置了 connect-timeout = 5 秒，网络不佳的环境可以适当调大。

总结：三步完成 Nix 构建加速 🚀

声明缓存：在 flake 的 nixConfig 中加入 extra-substituters 与 extra-trusted-public-keys；
构建系统：使用 nixos-raspberrypi.lib.nixosSystem 系列辅助函数，trustCaches 默认开启，缓存自动注入目标系统；
核对覆盖范围：按需参考 devshells/nix-build-to-cachix.nix 中的清单，确认你要的包是否已被预构建。

配合 README.md 中的模块说明，你现在已经可以在树莓派上用声明式方式快速搭建 NixOS 了——把等待编译的时间，省下来跑你的项目吧！