lazy-trees 与大规模仓库求值：只取所需的文件树

① 获取输入：把 flake 输入（本地路径 / git 仓库 / github:）变成 /nix/store 里的源码树
② 求值    ：把 .nix 表达式算成 derivation（.drv）
③ 构建    ：按 .drv 执行构建脚本，或从二进制缓存下载

builtins.fetchTree {
  type = "github";
  owner = "NixOS";
  repo = "nixpkgs";
  rev = "24.11";
}

outPath      : store 里的路径（可用于 import / 拼接）
narHash      : 整棵树的哈希（SRI 或 base32）
rev          : 解析后的 commit
lastModified : 提交时间戳（参与 SOURCE_DATE_EPOCH 推导）
shortRev     : 短 hash，便于日志阅读

# flake.nix 里绝大多数 import 只碰一两个文件
let
  lib = import (nixpkgs + "/lib");            # 读 lib/default.nix
  pkg = pkgs.callPackage ./pkgs/foo { };      # 读本地路径
in pkg

/nix/store/<hash>-source      ← 逻辑上是一棵树，物理上可能是按需填充的
  ├── flake.nix               ← 被读过 → 已取回
  ├── lib/                    ← 部分取回
  └── pkgs/                   ← 未读 → 尚未取回

① 求值器读 /nix/store/<hash>-source/lib/default.nix
② nix-daemon 查 tree 元数据：该文件在源仓库中的 blob 哈希
③ 若本地已有该 blob → 直接返回
④ 否则从源（本地 git 对象库 / GitHub API / codeload）取回并写入 store
⑤ 返回文件内容

# 惰性树与全量树产出的 narHash 必须相同
# 否则同一份输入会得到两个 store 路径 → 缓存命中率崩塌
nix flake metadata github:NixOS/nixpkgs --json | jq -r '.locks.nodes.nixpkgs.locked.narHash'

惰性树的代价：
  ✗ 每个文件的首次读取都有一次元数据查询（本地 git 很快，远端 API 有延迟）
  ✗ 若某操作遍历整棵树，仍然要全量取回，只是取回时机被推迟
  ✗ 远端源（github:）会受 API 速率限制影响，需配置 access-tokens

# 临时开启
nix --extra-experimental-features "nix-command flakes lazy-trees" flake show

# 永久写入配置
cat >> ~/.config/nix/nix.conf <<'EOF'
experimental-features = nix-command flakes lazy-trees
EOF

{
  nix.settings.experimental-features = [ "nix-command" "flakes" "lazy-trees" ];
}

# 方式一：看输入的类型与 narHash 是否已解析
nix flake metadata . --json | jq '.locks.nodes | to_entries[] | {k:.key, t:.value.locked.type}'

# 方式二：观察 store 里输入路径的实际大小
nix path-info -S $(nix flake metadata . --json | jq -r '.path')

# 方式三：在求值统计里看 fetch 次数
NIX_SHOW_STATS=1 nix eval --raw .#foo.name 2>&1 | grep -i fetch

早期：lazy-trees 必须显式加入 experimental-features，未开启时退回全量物化
后续：新版 Nix 对 flake 输入默认采用惰性求值，无需手工开启
排查：若行为与文档不符，先确认 nix --version 与 settings 中的 experimental-features

# 反例：把 nixpkgs 用 path: 引进来，惰性树完全失效
inputs.nixpkgs.url = "path:/home/me/nixpkgs";

# 正例：用 git+file 指向本地 checkout
inputs.nixpkgs.url = "git+file:///home/me/nixpkgs";

# github: 输入在惰性取回时会调用 GitHub API，未认证时速率很低
cat >> ~/.config/nix/nix.conf <<'EOF'
access-tokens = github.com=ghp_xxxxxxxxxxxxxxxx
EOF

eval-cache 键 = flake 指纹（self 的 rev/narHash + 相关输入指纹） + 属性路径
eval-cache 值 = 该属性路径求值出的值（如 drvPath、outPath、字符串）
存储位置      = ~/.cache/nix/eval-cache-v5/*.sqlite

# 关闭缓存，用于排查「缓存导致结果不更新」
nix eval --no-eval-cache --raw .#foo.name

# 打开求值统计，确认命中情况
NIX_SHOW_STATS=1 nix eval --raw .#foo.drvPath

# 查看缓存目录大小
du -sh ~/.cache/nix/eval-cache-v5

失效触发：
  - self 的源码树指纹变化（改了任何被追踪的文件）
  - 上游输入被更新（flake.lock 变化）
  - 显式 --no-eval-cache 或缓存文件被删除
不失效：
  - 仅修改了未被 git 追踪的文件（脏文件不在指纹内，注意这会造成困惑）

✗ nix flake archive              # 显式归档整棵树，必然全量
✗ nix flake check（在 nixpkgs 上）# 遍历所有输出
✗ builtins.readDir 递归遍历整棵树
✗ lib.fileset 对整棵树做 toSource / 过滤
✗ nix store prefetch-file 之类对目录整体的操作
✗ 把 outPath 直接当 path: 传下去（会退化为物化整树）

# 反模式：为了取一个版本号，先遍历整棵树
version = lib.strings.fileContents (nixpkgs + "/.version");
# 这条本身只读一个文件，是 OK 的

# 真正的反模式：对整棵树做 readDir 统计
allFiles = builtins.attrNames (builtins.readDir nixpkgs);   # 触发根目录枚举
recursive = builtins.readDir (nixpkgs + "/pkgs");           # 触发子树枚举

# 观察 store 中输入路径的实际磁盘占用随时间变化
watch -n1 "du -sh /nix/store/*-source 2>/dev/null | tail -5"

# 或者用 path-info 看闭包大小
nix path-info -S ./result

# monorepo 内部互引：优先 git+file，避免 path: 导致全量复制
inputs.shared.url = "git+file:///srv/repos/shared?ref=main";

# 上游依赖：用 github: 并配 access-tokens
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";

# 只需要一个文件而不需要 flake 输出时，用 flake = false
inputs.scripts.url = "github:me/scripts";
inputs.scripts.flake = false;

思路：让「常用属性」只依赖少量文件
  - 把版本号、常量抽到独立的 version.nix，避免 import 整个 pkgs 目录
  - 用 flake-parts / perSystem 把输出按系统切分，`nix flake show` 只求值一层
  - 避免在 flake.nix 顶层做昂贵计算（顶层表达式每次求值都会跑）

# 伪代码：先暖输入，再离线求值，最后构建
- run: nix flake metadata --json > /tmp/meta.json      # 解析输入
- run: nix flake archive --to /tmp/store-cache          # 可选：显式归档输入
- run: nix eval --raw .#packages.x86_64-linux.foo.drvPath
- run: nix build --print-build-logs .#packages.x86_64-linux.foo

# 1) 本地 git 源：改文件后无需重新下载，只重新求值
# 2) 常驻 daemon：nix-daemon 会缓存 tree 元数据
# 3) 关闭无谓的 flake show：用 nix eval 精确取需要的属性
nix eval --raw .#packages.x86_64-linux.myapp.version

症状：改了文件，求值结果没变
原因：文件未被 git 追踪 → 不在源码树指纹内 → eval-cache 未失效
处理：git add 该文件；或临时 nix eval --no-eval-cache 验证

# 现象：nix flake show 偶发几十秒延迟
# 原因：GitHub API 未认证时的速率限制
curl -sI https://api.github.com/rate_limit | head -1
# 处理：配置 access-tokens

nix build --offline .#foo
# error: file 'lib/default.nix' does not exist in the store

症状：同一 flake.lock，两次构建产物哈希不同
排查：确认输入 narHash 是否一致（nix flake metadata --json）
     若 narHash 一致而产物不同，问题不在惰性树，而在构建脚本的不确定性

风险：A 开启惰性树、B 未开启 → 差异只体现在耗时与网络请求上，store 路径一致
结论：惰性树不改变可复现性，可以放心让团队渐进启用