nixos-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring NixOS Systems with Flakes

使用Flakes配置NixOS系统

Configure NixOS systems with flakes, manage overlays properly, and structure configurations for maintainability.

使用Flakes配置NixOS系统，正确管理覆盖层（overlays），并构建具备可维护性的配置结构。

Core Principle

核心原则

Understand the interaction between NixOS system configuration and Home Manager overlays.

When

useGlobalPkgs = true

, overlays must be defined at the NixOS configuration level, not in Home Manager configuration files.

理解NixOS系统配置与Home Manager覆盖层之间的交互逻辑。

当

useGlobalPkgs = true

时，覆盖层必须在NixOS配置层面定义，而非Home Manager配置文件中。

When to Use

适用场景

Configuring NixOS with flakes and Home Manager
Adding overlays that don't seem to apply
Using
```
useGlobalPkgs = true
```
with custom overlays
Structuring NixOS configurations across multiple hosts
Package changes not appearing after rebuild
Confused about where to define overlays

Don't use for:

Packaging new software (use nix-packaging-best-practices)
Simple package installation without overlays
NixOS module development (see NixOS module documentation)

使用Flakes和Home Manager配置NixOS
添加的覆盖层似乎未生效
搭配自定义覆盖层使用
```
useGlobalPkgs = true
```
跨多台主机构建NixOS配置结构
重建系统后软件包变更未生效
不清楚应在何处定义覆盖层

不适用场景：

打包新软件（请使用nix-packaging-best-practices）
无需覆盖层的简单软件包安装
NixOS模块开发（请参阅NixOS模块文档）

Quick Reference

快速参考

Topic	Rule File
Overlay scope and useGlobalPkgs	overlay-scope
Flakes configuration structure	flakes-structure
Host configuration organization	host-organization
Package installation best practices	package-installation
Common configuration mistakes	common-mistakes
Debugging configuration issues	troubleshooting

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

Essential Pattern: Overlay with useGlobalPkgs

核心模式：搭配useGlobalPkgs使用覆盖层

nix

undefined

nix

undefined

❌ WRONG: Overlay in home.nix (doesn't apply)

❌ 错误：在home.nix中定义覆盖层（不生效）

home-manager/home.nix

{ nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; # Ignored! home.packages = with pkgs; [ claude-code ]; # Not found! }

{ nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; # 被忽略！ home.packages = with pkgs; [ claude-code ]; # 找不到该软件包！ }

✅ CORRECT: Overlay in NixOS home-manager block

✅ 正确：在NixOS的home-manager块中定义覆盖层

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 ]; }

undefined

{ home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; home-manager.users.chumeng = import ./home.nix; home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };

当useGlobalPkgs = true时，必须在此处定义覆盖层

nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; }

undefined

Common Tasks

常见任务

Task	Solution
Add flake input	Add to `inputs` in flake.nix
Add overlay for system packages	Define in `nixpkgs.overlays` in system configuration
Add overlay for home-manager (useGlobalPkgs=true)	Define in `home-manager.nixpkgs.overlays` in host config
Add overlay for home-manager (useGlobalPkgs=false)	Define in `home.nix` with `nixpkgs.overlays`
Pass inputs to modules	Use `specialArgs` in nixosSystem or home-manager
Multiple host configurations	Create separate host files in `hosts/`
Shared configuration modules	Create modules in `modules/` and import in each host
Package not found after overlay	Check overlay scope vs useGlobalPkgs setting

任务	解决方案
添加Flake输入源	在flake.nix的 `inputs` 中添加
为系统软件包添加覆盖层	在系统配置的 `nixpkgs.overlays` 中定义
为Home Manager添加覆盖层（useGlobalPkgs=true）	在主机配置的 `home-manager.nixpkgs.overlays` 中定义
为Home Manager添加覆盖层（useGlobalPkgs=false）	在 `home.nix` 中通过 `nixpkgs.overlays` 定义
将输入源传递给模块	在nixosSystem或home-manager中使用 `specialArgs`
多主机配置	在 `hosts/` 目录下创建独立的主机文件
共享配置模块	在 `modules/` 目录下创建模块，并在各主机配置中导入
添加覆盖层后仍找不到软件包	检查覆盖层作用域与useGlobalPkgs设置是否匹配

Overlay Scope Decision Matrix

覆盖层作用域决策矩阵

useGlobalPkgs	Overlay Definition Location	Affects
`true`	`home-manager.nixpkgs.overlays`	System + Home Manager packages
`true`	`home.nix` with `nixpkgs.overlays`	Nothing (ignored!)
`false`	`home.nix` with `nixpkgs.overlays`	Home Manager packages only
`false`	`home-manager.nixpkgs.overlays`	Home Manager packages only
Any	System `nixpkgs.overlays`	System packages only

useGlobalPkgs	覆盖层定义位置	影响范围
`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`	仅系统软件包

Configuration Layers (Bottom to Top)

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

System configuration (
```
/etc/nixos/configuration.nix
```
or host files)
- System-wide services
- System packages
- System overlays only affect this layer
Home Manager (useGlobalPkgs=true)
- Uses system pkgs (includes system overlays)
- Home Manager overlays affect both system and user packages
- Most efficient for single-user systems
Home Manager (useGlobalPkgs=false)
- Creates separate pkgs instance
- Home Manager overlays affect user packages only
- Useful for multi-user systems with different needs

系统配置（
```
/etc/nixos/configuration.nix
```
或主机文件）
- 系统级服务
- 系统软件包
- 系统覆盖层仅影响此层级
Home Manager（useGlobalPkgs=true）
- 使用系统软件包集合（包含系统覆盖层）
- Home Manager覆盖层影响系统与用户软件包
- 对单用户系统而言效率最高
Home Manager（useGlobalPkgs=false）
- 创建独立的软件包集合实例
- Home Manager覆盖层仅影响用户软件包
- 适用于需求不同的多用户系统

Red Flags - STOP

危险信号 - 立即停止

"Overlay in home.nix isn't working" → Check if useGlobalPkgs=true, move to host config
"I'll just add overlays everywhere" → Define once at appropriate scope
"Package works in nix repl but not installed" → Check overlay scope
"Changes don't apply after rebuild" → Verify overlay is in correct location
"useGlobalPkgs=false for no reason" → Use true unless you need separate package sets

"home.nix中的覆盖层不生效" → 检查是否设置了useGlobalPkgs=true，若为是则移至主机配置
"我要在所有地方都加覆盖层" → 在合适的作用域中定义一次即可
"软件包在nix repl中可用但无法安装" → 检查覆盖层作用域
"重建系统后变更未生效" → 验证覆盖层是否在正确位置
"无理由设置useGlobalPkgs=false" → 除非需要独立的软件包集合，否则请设置为true

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读各独立规则文件以获取详细说明与代码示例：

rules/overlay-scope.md       # 核心的覆盖层作用域问题
rules/flakes-structure.md    # 如何组织flake.nix
rules/host-organization.md   # 如何构建主机配置结构
rules/common-mistakes.md     # 常见陷阱及规避方法

每个规则文件包含：

简要说明其重要性
错误代码示例及解释
正确代码示例及解释
额外背景信息与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有扩展规则的完整指南，请查看：

AGENTS.md