⚡

Nix包与配置管理器Skill nix-manager

这是一个用于管理Nix包、flakes和配置的技能，遵循Determinate Nix安装器的最佳实践，用于安装/更新包、创建flakes、解决Nix问题或优化Nix工作流程。关键词：Nix, 包管理, flake, nixpkgs, 配置管理, 自动化部署, DevOps

DevOps 0 次安装 0 次浏览 更新于 3/20/2026

名称：nix-manager 描述：使用Determinate Nix安装器模式管理Nix包、flakes和配置。适用于安装/更新包、创建flakes、解决Nix问题或优化Nix工作流程。关键词：nix, flake, package, nixpkgs, nix profile, flake.nix, flake.lock, determinate, nix-installer

Nix包与配置管理器

遵循Determinate Systems最佳实践和此仓库模式的全面Nix管理。

指令

1. 理解仓库上下文

检查当前Nix设置：

  • Flake位置：/Users/wcygan/Development/dotfiles/flake.nix
  • 安装脚本：scripts/install-packages.sh
  • 包管理：nix profile（用户范围，现代方法）
  • 安装器：Determinate Systems安装器（macOS/Linux）
  • 更新机制：make update或nix flake update && nix profile upgrade

阅读当前flake.nix以理解：

  • 输入源（当前：nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"）
  • 包定义（buildEnv包含60+包）
  • 输出：packages, devShells, formatter
  • 支持的系统：x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin

2. 包管理操作

安装新包

流程：

  1. 在flake.nix的适当类别中添加包
  2. 运行nix flake check验证
  3. 运行nix profile upgrade dotfiles应用更改
  4. 测试包可用性

示例：

# flake.nix包部分
paths = [
  # ... 现有包 ...

  # 新包
  cowsay  # 有趣的终端工具
];

# 验证并安装
nix flake check
nix profile upgrade dotfiles
which cowsay  # 验证安装

更新所有包

流程：

# 更新flake输入（更新nixpkgs修订版）
nix flake update

# 应用更新到已安装的配置文件
nix profile upgrade dotfiles

# 验证无中断
nix profile list

或使用Makefile快捷方式：

make update  # 运行以上两个命令

移除包

流程：

  1. 从flake.nix中移除
  2. 运行nix flake check
  3. 运行nix profile upgrade dotfiles
  4. 旧包保留在存储中，但不在PATH中

注意：垃圾回收移除未引用的包：

make clean  # 或：nix-collect-garbage -d

3. Flake配置

修改flake.nix

常见操作：

添加新输入：

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  # 添加新输入
  home-manager.url = "github:nix-community/home-manager";
  home-manager.inputs.nixpkgs.follows = "nixpkgs";  # 防止重复nixpkgs
};

添加平台特定包：

paths = [
  # 通用包
  git gh lazygit
] ++ lib.optionals stdenv.isDarwin [
  # macOS专用
  darwin.apple_sdk.frameworks.Security
] ++ lib.optionals stdenv.isLinux [
  # Linux专用
  libnotify
];

修改devShell：

devShells = forAllSystems ({ pkgs }: {
  default = pkgs.mkShell {
    packages = with pkgs; [
      fish
      nixpkgs-fmt
      shellcheck
      # 在此添加开发工具
    ];
    inputsFrom = [ self.packages.${pkgs.system}.default ];
    shellHook = ''
      echo "🐠 点文件开发环境"
      echo "运行：make test-pre"
    '';
  };
});

验证Flake

应用前始终验证：

nix flake check        # 完整验证（慢，构建所有内容）
nix flake metadata     # 快速元数据检查
nix flake show         # 显示输出而无需构建

常见问题：

  • 包在nixpkgs中重命名（例如，du-dust → dust）
  • 包列表中缺少逗号
  • 无效属性路径
  • Nix表达式中的语法错误

更新锁文件

何时更新：

  • 定期维护（每周/每月）
  • 需要安全更新
  • 需要特定包版本

如何：

# 更新所有输入
nix flake update

# 仅更新特定输入
nix flake lock --update-input nixpkgs

# 验证更改
git diff flake.lock

4. 故障排除

Nix操作缓慢

诊断：

nix store info             # 检查存储大小
nix store gc --dry-run     # 查看可清理内容

解决方案：

  • 运行nix-collect-garbage -d移除旧生成
  • 运行nix store optimise去重文件
  • 检查网络连接（二进制缓存下载）

包未找到

错误：error: attribute 'package-name' missing

解决方案：

  1. 检查nixpkgs版本：某些包仅在unstable中
  2. 搜索包：nix search nixpkgs package-name
  3. 检查包是否重命名
  4. 尝试替代包名称

评估错误

错误：error: ... while evaluating ...

常见原因：

  • flake.nix中的语法错误
  • 递归属性访问
  • 类型不匹配（字符串与列表）

调试：

nix eval .#packages.aarch64-darwin.default.name  # 测试特定属性
nix repl                                          # 交互式REPL
:lf .                                             # 在REPL中加载flake
packages.aarch64-darwin.default.name              # 在REPL中评估

锁文件冲突

错误：error: flake.lock is dirty

解决方案：

# 重新生成锁文件
rm flake.lock
nix flake update

# 或接受未提交更改
nix flake check --impure  # 不推荐用于可重复性

配置文件问题

列出已安装的配置文件：

nix profile list

输出格式：

索引：              0
Flake属性：    legacyPackages.aarch64-darwin.dotfiles
原始flake URL： git+file:///Users/wcygan/Development/dotfiles
锁定flake URL：   git+file:///Users/wcygan/Development/dotfiles?rev=...
存储路径：        /nix/store/...-system-packages

回滚到前一生成：

nix profile rollback

移除特定配置文件：

nix profile remove <索引号>

5. CI/CD集成

此仓库使用Determinate Systems GitHub Actions进行CI。

GitHub Actions设置（.github/workflows/ci.yml）：

- name: 设置Nix缓存
  uses: DeterminateSystems/magic-nix-cache-action@v2

- name: 安装Nix
  uses: DeterminateSystems/nix-installer-action@v14
  with:
    extra-conf: |
      experimental-features = nix-command flakes

- name: 运行安装脚本
  run: ./install.sh

好处：

  • 魔法Nix缓存：约90%更快CI（使用GitHub Actions缓存）
  • 自动缓存填充
  • 无需配置

本地等价：

# 在Docker中测试安装
make test-docker

# 测试幂等性
./install.sh && ./install.sh  # 应成功两次

6. 最佳实践（Determinate Nix模式）

使用nixos-unstable而非master

原因：

  • nixos-unstable：经过测试，通过Hydra CI
  • master：未经测试，可能有损坏包

当前设置：

inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

永不使用–impure

**问题：**允许环境变量访问，破坏可重复性

正确：

nix profile add .              # 纯净评估
nix profile upgrade dotfiles   # 纯净评估

错误：

nix profile add . --impure     # 不好：不可重复

**例外：**仅当flake显式使用getEnv或类似功能时使用--impure

在锁文件中固定依赖

原因：

  • 确保跨机器的可重复构建
  • 防止“在我机器上可行”问题
  • CI/CD可靠性所需

如何：

# 始终提交flake.lock
git add flake.lock
git commit -m "chore: 更新flake锁"

对包组使用buildEnv

此仓库中的模式：

packages.default = pkgs.buildEnv {
  name = "system-packages";
  paths = [ git gh lazygit ... ];
};

好处：

  • 所有包的单一推导
  • 原子更新（所有包成功或失败一起）
  • 比单独的nix profile install调用更易管理

在配置中启用Flakes

用户级配置（~/.config/nix/nix.conf）：

experimental-features = nix-command flakes

这由scripts/install-packages.sh自动设置

7. 开发工作流

创建新项目Flake

使用仓库根目录作为模板：

# 复制flake结构
cp flake.nix /path/to/new-project/

# 为项目需求定制
cd /path/to/new-project
$EDITOR flake.nix

或使用模板目录：

# 使用模板（如果在.claude/skills/nix-manager/templates/中可用）
nix flake init -t .#template-name

本地测试Flake

无需安装：

# 进入开发shell
nix develop

# 构建而不安装
nix build

# 运行特定包
nix run .#package-name

格式化Nix代码

使用格式化器输出：

nix fmt  # 使用nixpkgs-fmt（在flake.nix中定义）

手动格式化：

nixpkgs-fmt flake.nix

8. 迁移指导

从Homebrew迁移

不要卸载Homebrew—它和平共存。Fish PATH优先级：

  1. Homebrew（/opt/homebrew/bin）- 最高优先级
  2. 用户bin（~/.local/bin, ~/bin）
  3. 语言工具链（~/.cargo/bin, ~/go/bin）
  4. Nix（~/.nix-profile/bin）- 最低优先级

迁移策略：

# 1. 通过Nix安装包
# （添加到flake.nix并运行nix profile upgrade）

# 2. 测试包工作
which package-name  # 应显示Homebrew路径（更高优先级）

# 3. 从Homebrew卸载
brew uninstall package-name

# 4. 验证Nix版本现在激活
which package-name  # 应显示/nix/store/...路径

从apt/dnf迁移

Linux发行版：

  • Nix与系统包管理器共存
  • 系统包优先于Nix（通过PATH排序）
  • 使用Nix用于发行版仓库中没有或需要新版本的工具

9. 输出格式

修改flake.nix时：

使用编辑工具处理现有文件：

  • 修改特定部分
  • 保留注释和格式
  • 最小化差异大小

使用写入工具处理新文件：

  • 从头开始创建完整flake.nix
  • 包含解释选择的注释
  • 遵循仓库格式风格

更改后，始终：

  1. 验证：nix flake check
  2. 测试构建：nix build --dry-run
  3. 应用：nix profile upgrade dotfiles
  4. 验证：nix profile list

包含测试命令：

# 验证更改
nix flake check

# 显示更改内容
nix flake show

# 应用更新
nix profile upgrade dotfiles

仓库模式

此点文件仓库遵循以下约定：

文件结构：

  • flake.nix - 包定义和输出
  • flake.lock - 固定依赖版本
  • scripts/install-packages.sh - 安装包装器
  • scripts/link-config.sh - 点文件符号链接
  • config/ - 点文件配置（fish, starship等）

包组织： 包按用途分组并带有注释：

paths = [
  # 版本控制
  git gh lazygit

  # 构建工具
  gnumake cmake pkg-config

  # 编程语言
  rustup go python3 deno

  # ... 等等
];

测试：

  • make test-pre - 预飞验证
  • make test-local - 临时HOME测试
  • make test-docker - 多发行版Docker矩阵

常见命令：

  • make install - 运行完整安装
  • make update - 更新flake并升级包
  • make clean - 垃圾回收
  • make verify - 检查Nix安装健康状态

参考文档

快速参考

基本命令：

# 包管理
nix search nixpkgs <package>     # 搜索包
nix profile list                 # 列出已安装包
nix profile upgrade dotfiles     # 应用flake更改
nix-collect-garbage -d           # 清理旧生成

# Flake管理
nix flake update                 # 更新所有输入
nix flake check                  # 验证flake
nix flake show                   # 显示输出
nix flake metadata               # 显示元数据

# 开发
nix develop                      # 进入开发shell
nix build                        # 构建包
nix fmt                          # 格式化Nix代码
nix run .#package                # 运行包

# 故障排除
nix store info                   # 存储统计
nix store gc --dry-run           # 预览清理
nix profile rollback             # 回滚到前一版本