nix-darwin 是一套面向 macOS 的 dotfiles 配置方案，使用 Nix flakes 与 home-manager 管理 macOS 系统与用户环境。
架构
整体为三层系统：darwin 模块（系统层）→ home-manager（用户层）→ homebrew（GUI 应用层）。
flake.nix 作为轻量编排层，下辖两个主机：
- hosts/workstation/：使用 unstable 包与完整工具链。default.nix 指向 modules/darwin/；home.nix 指向 modules/home-manager/base.nix 加各程序模块；homebrew.nix 指向 modules/homebrew/base.nix 加主机 casks。
- hosts/homelab/：使用 stable 包（macOS 13），配置最小化。default.nix 指向 modules/darwin/；darwin.nix 存放主机特定覆盖（mkForce）；home.nix 指向 modules/home-manager/base.nix 加 neovim-stable；homebrew.nix 同理。
完整的依赖流与模块分层见 references/architecture.md。
核心约定
程序开关模式
每个程序模块遵循统一结构（见 templates/program-module.nix）：
options.my.{program}.enable = mkEnableOption "description";
config = mkIf cfg.enable { /* config */ };
在主机 home.nix 中启用：
my.neovim.enable = true;
新增程序步骤
- 使用模板创建 modules/home-manager/programs/{name}.nix
- 在主机 home.nix 中导入
- 设置 my.{name}.enable = true
- 如需 GUI cask，加入 hosts/{host}/homebrew.nix
配置管理方式
| 方式 | 使用场景 | 示例 |
|---|---|---|
| mkOutOfStoreSymlink | 无需重建即可变更的配置 | nvim、hyprspace |
| builtins.readFile | 载入 nix store 的配置 | zed-editor |
| 内联 nix | 简单、nix 原生配置 | ghostty、starship |
命名约定
- Nix 文件：kebab-case.nix
- 模块选项：my.{program}.enable
- Dotfile 符号链接：symlink/ 下的 {name}.symlink
- 主机：kebab-case
- 提交：conventional（feat(neovim):、fix(darwin):）
常用命令
完整列表见 references/commands.md。
# 应用配置
sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#workstation
sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#homelab
# 仅校验不应用
nix flake check
# 更新 inputs
nix flake update
注意事项
详细说明与修复见 references/gotchas.md。
构建与系统：
- nix.daemonProcessType = "Background" 可避免构建期间 UI 卡顿
- Determinate Nix 与 nix-darwin 的 nix 管理冲突，需禁用其一
- follows 未正确设置会导致闭包体积膨胀
macOS 兼容性：
- homelab（macOS 13）需要 pkgs-stable，不要在该主机使用 unstable 包
- PAM 服务可能需要 lib.mkForce {} 覆盖 darwin 默认值
包管理：
- Neovim 的 tree-sitter CLI 必须在 extraPackages 中显式声明（不会自动包含）
- Homebrew cleanup 可能移除 nix 管理的包，需禁用 autoCleanup
- Homebrew cask 与 nixpkgs 取舍：CLI 工具优先 nixpkgs，GUI 应用优先 homebrew
Nix 模式：
- mkForce 与 mkDefault：mkForce 优先级最高，谨慎使用
- mkOutOfStoreSymlink 路径必须是绝对字符串，不能是 nix path
社区模式
当用户询问改进或替代方案时，可参考 references/community-patterns.md。高星仓库中的关键模式包括：
- mkDarwinConfig 辅助函数：减少 flake.nix 样板（malob、kclejeune）
- 多通道 overlay：任意位置使用 pkgs.stable.X 对比 specialArgs（malob）
- 自动导入模块：目录扫描消除手动导入列表（wimpysworld）
- 基于标签的特性：声明主机“是什么”而非“有什么”（wimpysworld）
- primaryUser 别名：写 hm.programs.X 而非完整路径（kclejeune）
- flake 中的 treefmt：deadnix + nixfmt + statix（kclejeune）
- 自动化 flake lock 更新：CI 自动 PR 加自动合并（wimpysworld）