扩展 Hjem 指南:如何编写自定义模块,打造你的 dotfiles 模块系统

原创2026-11-01 09:23:102,000 阅读

扩展 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)确认无误再正式切换。

延伸资源:文档与源码路径

想深入,下面这份清单按"从文档到源码"的顺序整理好了 📁:

如需本地克隆源码,仓库地址为 https://gitcode.com/gh_mirrors/hje/hjem。

✅ 小结:扩展 Hjem 的核心,就是"定义 options + 用 config 生成文件",再用 hjem.extraModules 接入。掌握这两步,你就能把 dotfiles 从一堆散落文件,升级成一套优雅、可复用、可分享的模块系统。

登录后查看全文
hjem