重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
nixos-best-practices by lihaoze123/my-skills
npx skills add https://github.com/lihaoze123/my-skills --skill nixos-best-practices使用 flakes 配置 NixOS 系统,正确管理 overlays,并构建可维护的配置结构。
在进行任何 NixOS 配置更改之前,您必须:
在阅读完适用的文档之前,请勿开始编码。
大多数配置错误源于没有先阅读规则。您花 5 分钟阅读将节省数小时的调试时间。
理解 NixOS 系统配置与 Home Manager overlays 之间的交互。
当 useGlobalPkgs = true 时,overlays 必须在 NixOS 配置级别定义,而不是在 Home Manager 配置文件中。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
useGlobalPkgs = true 与自定义 overlays 结合使用不适用于:
| 主题 | 规则文件 |
|---|---|
| Overlay 作用域和 useGlobalPkgs | overlay-scope |
| Flakes 配置结构 | flakes-structure |
| 主机配置组织 | host-organization |
| 包安装最佳实践 | package-installation |
| 常见配置错误 | common-mistakes |
| 调试配置问题 | troubleshooting |
# ❌ 错误:在 home.nix 中定义 Overlay(不会生效)
# home-manager/home.nix
{
nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; # 被忽略!
home.packages = with pkgs; [ claude-code ]; # 找不到!
}
# ✅ 正确:在 NixOS 的 home-manager 块中定义 Overlay
# 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; };
# 当 useGlobalPkgs = true 时,Overlay 必须定义在这里
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 定义 |
| 将 inputs 传递给模块 | 在 nixosSystem 或 home-manager 中使用 specialArgs |
| 多主机配置 | 在 hosts/ 目录下创建单独的主机文件 |
| 共享配置模块 | 在 modules/ 目录下创建模块并在每个主机中导入 |
| 添加 overlay 后找不到包 | 检查 overlay 作用域与 useGlobalPkgs 设置 |
| 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 | 仅系统包 |
/etc/nixos/configuration.nix 或主机文件) * 系统范围的服务
* 系统包
* 系统 overlays 仅影响此层
2. Home Manager (useGlobalPkgs=true)
* 使用系统 pkgs(包含系统 overlays)
* Home Manager overlays 同时影响系统和用户包
* 对于单用户系统最有效
3. Home Manager (useGlobalPkgs=false)
* 创建独立的 pkgs 实例
* Home Manager overlays 仅影响用户包
* 适用于需求不同的多用户系统
阅读各个规则文件以获取详细解释和代码示例:
rules/overlay-scope.md # 核心的 overlay 作用域问题
rules/flakes-structure.md # 如何组织 flake.nix
rules/host-organization.md # 如何构建主机配置
rules/common-mistakes.md # 陷阱及如何避免
每个规则文件包含:
获取包含所有规则扩展的完整指南:AGENTS.md
每周安装次数
54
代码仓库
GitHub 星标数
2
首次出现
2026年1月24日
安全审计
安装于
opencode47
gemini-cli46
codex44
github-copilot43
kimi-cli38
amp37
Configure NixOS systems with flakes, manage overlays properly, and structure configurations for maintainability.
BEFORE making ANY NixOS configuration changes, you MUST:
Do NOT start coding until you've read the applicable documentation.
Most configuration errors happen from not reading the rules first. The 5 minutes you spend reading will save hours of debugging.
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.
useGlobalPkgs = true with custom overlaysDon't use for:
| 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 |
# ❌ 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 ];
}
| 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 |
| 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 |
System configuration (/etc/nixos/configuration.nix or host files)
Home Manager (useGlobalPkgs=true)
Home Manager (useGlobalPkgs=false)
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:
For the complete guide with all rules expanded: AGENTS.md
Weekly Installs
54
Repository
GitHub Stars
2
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode47
gemini-cli46
codex44
github-copilot43
kimi-cli38
amp37
Angular编译器CLI (ngtsc) 架构详解:Ivy编译、模板类型检查与AOT
516 周安装
TypeScript 最佳实践指南:常量类型、扁平化接口、工具类型与严格模式
206 周安装
营销分析师AI工具:营销活动绩效分析、归因建模与预算优化指南
206 周安装
get-available-resources:自动检测CPU/GPU/内存/磁盘资源,为科学计算提供策略建议
209 周安装
Figma MCP 集成指南:AI 驱动设计转代码,实现 React + Tailwind 精准开发
208 周安装
Proxmox VE 命令行管理指南:qm、pct 工具详解与虚拟机容器自动化
208 周安装
Handoff - Claude会话轮换工具:无缝交接工作上下文,突破令牌限制
207 周安装
| 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 |
nixpkgs.overlays| Home Manager packages only |
false | home-manager.nixpkgs.overlays | Home Manager packages only |
| Any | System nixpkgs.overlays | System packages only |