nixos-best-practices

使用 Flakes 配置 NixOS 系统

使用 flakes 配置 NixOS 系统，妥善管理 overlays，并构建易于维护的配置结构。

⚠️ 关键：更改前请先阅读

在进行任何 NixOS 配置更改之前，必须：

1. 查阅下方快速参考中的相关规则文件
2. 检查 common-mistakes.md，避免已知问题
3. 检查 troubleshooting.md，了解系统化的调试方法
4. 遵循代码库中的现有模式

阅读适用文档之前，请勿开始编码。

大多数配置错误都是因为没有先阅读规则。花 5 分钟阅读文档，可以省下数小时的调试时间。

警示信号——编码前请停止

• “我可以直接试试这个选项” → 先检查 nixpkgs/Home Manager 中是否存在此选项
• “我来试试几种不同的方法” → 阅读文档，不要猜测
• “这样应该能行” → 验证语法，并确认此选项在 nixpkgs 中可用
• 多次尝试重建 → 你缺少系统化的调试方法
• “我记得这样能用” → 文档会更新，请确认当前的方法

核心原则

理解 NixOS 系统配置与 Home Manager overlays 之间的相互作用。

当 useGlobalPkgs = true 时，必须在 NixOS 配置层级定义 overlays，而不是在 Home Manager 配置文件中定义。

适用场景

• 使用 flakes 和 Home Manager 配置 NixOS
• 添加似乎未生效的 overlays
• 将 useGlobalPkgs = true 与自定义 overlays 配合使用
• 跨多个主机构建 NixOS 配置
• 重建后软件包更改未生效
• 不确定应在哪里定义 overlays

不适用于：

• 打包新软件（请使用 nix-packaging-best-practices）
• 不使用 overlays 的简单软件包安装
• NixOS 模块开发（请参阅 NixOS 模块文档）

快速参考

主题	规则文件
Overlay 作用域和 useGlobalPkgs	overlay-scope
Flakes 配置结构	flakes-structure
主机配置组织方式	host-organization
软件包安装最佳实践	package-installation
常见配置错误	common-mistakes
配置问题调试	troubleshooting

基本模式：配合 useGlobalPkgs 使用 Overlay

# ❌ WRONG: Overlay in home.nix (doesn't apply)
# home-manager/home.nix
{
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];  # Ignored!
  home.packages = with pkgs; [ claude-code ];  # Not found!
}

# ✅ CORRECT: Overlay in NixOS home-manager block
# hosts/home/default.nix
{
  home-manager.useGlobalPkgs = true;
  home-manager.useUserPackages = true;
  home-manager.users.chumeng = import ./home.nix;
  home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };
  # Overlay must be HERE when useGlobalPkgs = true
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];
}

常见任务

任务	解决方案
添加 flake 输入	在 flake.nix 的 inputs 中添加
为系统软件包添加 overlay	在系统配置的 nixpkgs.overlays 中定义
为 home-manager 添加 overlay（useGlobalPkgs=true）	在主机配置的 home-manager.nixpkgs.overlays 中定义
为 home-manager 添加 overlay（useGlobalPkgs=false）	在 home.nix 中使用 nixpkgs.overlays 定义
向模块传递输入	在 nixosSystem 或 home-manager 中使用 specialArgs
配置多个主机	在 hosts/ 中创建单独的主机文件
共享配置模块	在 modules/ 中创建模块，并在各主机中导入
Overlay 后找不到软件包	检查 overlay 作用域与 useGlobalPkgs 设置是否匹配

Overlay 作用域决策矩阵

useGlobalPkgs	Overlay 定义位置	影响范围
true	home-manager.nixpkgs.overlays	系统和 Home Manager 软件包
true	home.nix 中的 nixpkgs.overlays	无影响（已忽略！）
false	home.nix 中的 nixpkgs.overlays	仅 Home Manager 软件包
false	home-manager.nixpkgs.overlays	仅 Home Manager 软件包
任意	系统的 nixpkgs.overlays	仅系统软件包

配置层级（从底层到顶层）

1. 系统配置（/etc/nixos/configuration.nix 或主机文件）

   • 系统范围的服务
   • 系统软件包
   • 系统 overlay 仅影响此层

2. Home Manager（useGlobalPkgs=true）

   • 使用系统 pkgs（包含系统 overlay）
   • Home Manager overlay 会同时影响系统和用户软件包
   • 对单用户系统最有效率

3. Home Manager（useGlobalPkgs=false）

   • 创建独立的 pkgs 实例
   • Home Manager overlay 仅影响用户软件包
   • 适用于需求不同的多用户系统

危险信号——停止操作

• “home.nix 中的 Overlay 不起作用” → 检查 useGlobalPkgs=true 是否已启用，并将其移至主机配置
• “我只要到处添加 overlay 就行了” → 在适当的作用范围内定义一次
• “软件包在 nix repl 中可用，但未安装” → 检查 overlay 的作用范围
• “重建后更改没有生效” → 确认 overlay 位于正确位置
• “没有理由却设置 useGlobalPkgs=false” → 除非需要独立的软件包集，否则使用 true

使用方法

阅读各规则文件，了解详细说明和代码示例：

rules/overlay-scope.md       # The core overlay scope issue
rules/flakes-structure.md    # How to organize flake.nix
rules/host-organization.md   # How to structure host configs
rules/common-mistakes.md     # Pitfalls and how to avoid them

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料

完整编译文档

如需查看包含所有规则详解的完整指南：AGENTS.md