扩展 Hjem 指南:如何编写自定义模块,打造你的 dotfiles 模块系统
扩展 Hjem 指南:如何编写自定义模块,打造你的 dotfiles 模块系统
Hjem 是一个用 Nix 管理 $HOME 与 dotfiles 的模块系统。本文将带你扩展 Hjem、编写自定义模块,把零散的 dotfiles 组织成一套可复用、可分享的 dotfiles 模块系统。你只需掌握 options + config 两个部件,再配合 hjem.extraModules,几分钟就能拥有属于自己、且能交给别人复用的模块。
Hjem 是什么?先看懂这个 $HOME 管理模块系统
Hjem(丹麦语"home")定位很纯粹:用 Nix 以清单(manifest)方式安全地把文件链接进用户主目录,而不是一堆复杂的 API。它的设计哲学可以概括为三点 🎯:
- 极简代码、最少抽象 —— 不内置一堆应用模块,把应用层抽象交给你自己决定
- 多用户、开箱即用 —— 天生支持任意数量的用户
- 为扩展而生 —— 官方刻意保持核心最小化,正是为了让"自定义模块"成为一等公民
💡 换句话说:Hjem 只负责"把文件正确放进
$HOME"这件最底层的事;至于"如何管理 nvim / fzf / 编辑器"这类应用抽象,就该由你来写模块实现。这就是本文要教你的事。
相关实现与理念,可参阅 README.md 与官方扩展文档 docs/inputs/extending.md。
什么是 Hjem 模块:options 与 config 两大核心
Hjem 的模块完全复用 NixOS 模块系统的语法,因此你会感觉非常亲切。一个合格的 Hjem 模块,本质上只有两个部件 🧩:
| 部件 | 作用 | 谁来读它 |
|---|---|---|
options |
声明对外暴露的配置项(如 enable、package) |
用户在配置里填写 |
config |
根据 options 生成文件、软件与行为 |
Hjem 在构建时求值 |
下面是一个最小可运行示例,命名为 modules/myapp.nix,它会管理一个叫 myapp 的程序配置:
# modules/myapp.nix —— 你的第一个 Hjem 自定义模块
{ lib, pkgs, config, ... }:
let
# 把本模块的选项收敛到 cfg,config 里引用更方便
cfg = config.programs.myapp;
in {
# ── 1) options:暴露给用户的配置项 ──────────────
options.programs.myapp = {
enable = lib.mkEnableOption "myapp 管理";
package = lib.mkPackageOption pkgs "myapp" { nullable = true; };
};
# ── 2) config:根据选项生成文件与行为 ────────────
config = lib.mkIf cfg.enable {
# 文件直接相对用户 $HOME,无需关心绝对路径
files = {
# 用 TOML 生成器把 Nix 值转成配置文件
".config/myapp/config.toml" = {
generator = (pkgs.formats.toml { }).generate "config";
value = { mode = "dark"; language = "zh-CN"; };
};
# 直接写一段文本
".config/myapp/myapp.conf".text = "key=value\n";
};
# 可选:借助 Hjem 安装用户级软件
packages = lib.optional (cfg.package != null) cfg.package;
};
}
文件字段支持三种来源:text(纯文本)、source(store 路径/目录)、generator(把 Nix 值转换为文件,可配合 pkgs.formats 输出 JSON/YAML/TOML 等)。其完整字段定义见 lib.nix。
第二步:用 hjem.extraModules 把模块接入配置
模块写好后,还需要"注册"进 Hjem。扩展 Hjem 的钥匙就是 hjem.extraModules 选项(定义于 modules/common/top-level.nix)。
⚠️ 一个关键细节:extraModules 中的每个模块会被放进每个启用用户的 Hjem 子模块内求值(注入点见 modules/nixos/base.nix)。因此:
- 你暴露的命名空间
programs.myapp,实际会挂在hjem.users.<username>.programs.myapp下 - 你在
config里写的files,会直接成为该用户要管理的文件
据此,在你的系统配置(如 configuration.nix)中这样接入:
# 在你的 NixOS 系统模块中
{ inputs, pkgs, ... }: {
imports = [ inputs.hjem.nixosModules.default ];
hjem = {
# 1. 注入自定义模块(每个启用用户下都会求值)
extraModules = [ ./modules/myapp.nix ];
# 2. 在"用户"命名空间下启用模块并配置选项
users.alice = {
directory = "/home/alice";
programs.myapp = {
enable = true;
package = pkgs.myapp;
};
};
};
}
💡 命名空间完全由你决定:
programs.myapp、tools.myapp、mymodule.programs.fzf-yay都合法,只要不和已有选项冲突即可。
进阶:导出 hjemModules,与社区共享模块
想让同事或社区也用你的模块?只需在 flake 里把模块作为独立输出发布,别人加进 hjem.extraModules 就能用 🚀:
# flake.nix(节选)
outputs = { self, ... }: {
# 发布自定义模块,名字任意
hjemModules = {
myapp = ./modules/myapp.nix;
default = self.hjemModules.myapp;
};
};
Hjem 本身即通过 nixosModules / darwinModules / finixModules 三种入口对外暴露模块,定义见 flake.nix。你的模块完全可以照此思路,成为别人配置里的一个 input。
常见问题与注意事项
- 作用域是"用户级":
extraModules会在每个启用用户下求值,多用户时会被分别评估,命名空间挂在该用户名下。 - 传额外参数:模块里若要访问
inputs等,请通过hjem.specialArgs传入,见 modules/common/top-level.nix。 - 精细控制:善用
lib.modules的mkIf/mkAfter/mkMerge组织行为,这是写出健壮模块的常用手法。 - 文件类型:除来源字段外,还支持
type(symlink/copy/delete/directory/modify)、permissions、executable、clobber等,详见 lib.nix。 - 验证:改完运行
nixos-rebuild build(或dry-activate)确认无误再正式切换。
延伸资源:文档与源码路径
想深入,下面这份清单按"从文档到源码"的顺序整理好了 📁:
- 官方扩展文档(含完整 FZF 模块范例):docs/inputs/extending.md
- 官方安装 / 用法文档:docs/inputs/index.md
hjem.extraModules选项定义:modules/common/top-level.nix- 每用户选项(files / xdg / packages / environment):modules/common/user.nix
- 模块注入点(NixOS):modules/nixos/base.nix
- 文件字段与类型定义:lib.nix
- 模块入口导出(nixos / darwin / finix):flake.nix
- 使用测试示例:tests/nixos/basic.nix
- manifest 校验 schema:manifest/v3.cue
如需本地克隆源码,仓库地址为
https://gitcode.com/gh_mirrors/hje/hjem。
✅ 小结:扩展 Hjem 的核心,就是"定义 options + 用 config 生成文件",再用 hjem.extraModules 接入。掌握这两步,你就能把 dotfiles 从一堆散落文件,升级成一套优雅、可复用、可分享的模块系统。