Home Manager 26.05 版本发布全览：SSH RFC 42、按需激活、模块化服务与关键变更迁移指南

Home Manager 26.05 版本发布全览：SSH RFC 42、按需激活、模块化服务与关键变更迁移指南

【免费下载链接】home-managerManage a user environment using Nix [maintainer=@khaneliman, @rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager

Home Manager 26.05 稳定版发布于 2026 年 5 月，是该项目一次覆盖面极广的里程碑式发布。本指南以 docs/release-notes/rl-2605.md 为骨架，逐条解读本次发布的 Highlights 与 State Version 变更，并结合仓库源码说明新选项的底层实现、迁移路径与配置示例，帮助你在升级到home.stateVersion = "26.05"时顺利完成配置迁移。

RFC 42 风格的 SSH 配置：programs.ssh.settings

26.05 起，Home Manager 支持以 RFC 42 风格声明式配置 OpenSSH：

programs.ssh.settings = { Host "github.com" = { IdentityFile = "~/.ssh/id_ed25519"; User = "git"; }; };

• 旧格式programs.ssh.matchBlocks已被标记为废弃，并会在配置求值时自动迁移（见 modules/programs/ssh.nix 中matchBlocks选项与lib.mapAttrs自动转换逻辑）。
• 迁移时，matchBlocks.<name>.extraOptions中的指令需要按上游 OpenSSH 指令名（ssh_config(5)）写入settings；同时设置host与match的旧块会触发警告（见 modules/programs/ssh.nix）。
• settings选项定义于 modules/programs/ssh.nix，支持地址、端口、动态转发等结构化子选项，programs.ssh.settings可直接覆盖旧配置的绝大部分能力。

home-manager.startAsUserService：登录时按需激活

新选项home-manager.startAsUserService（默认false）将每个用户的激活从系统启动阶段移到用户登录时按需执行，适用于 home 目录在登录后才挂载的场景（如pam_mount）。其实现位于 nixos/default.nix：

• 关闭时（默认），每个用户生成home-manager-<user>系统服务，在multi-user.target启动阶段运行，并设置RequiresMountsFor = homeDirectory（nixos/default.nix）。
• 开启时，生成统一的用户级服务systemd.user.services.home-manager，通过 drop-in（10-user-activation.conf）为每个用户注入ExecStart=${activationPackage}/activate，并在系统激活时用systemctl --user restart home-manager重载（nixos/default.nix）。

从源码看，该模式仍处于实验阶段：文档明确提示“多用户场景可能加速启动但尚未证实”，且依赖完整的 systemd 用户上下文，使用前请评估你的登录管理器是否满足条件。

新增home.services命名空间：接入 nixpkgs 模块化服务

本次发布新增home.services，即 nixpkgs「模块化服务」在用户域的等价物。来自包的pkgs.<name>.passthru.services.default可直接原样导入并提升为用户 systemd 单元，同一模块在 NixOS 与 Home Manager 上求值结果一致。完整说明见 docs/manual/usage/modular-services.md。

最小示例——以用户服务运行 mpd：

{ pkgs, ... }: { home.services.mpd = { process.argv = [ "${pkgs.mpd}/bin/mpd" "--no-daemon" ]; }; }

该配置生成~/.config/systemd/user/mpd.service，ExecStart指向 mpd 二进制，默认WantedBy=default.target。

关键语义：

• 每个服务暴露上游 NixOS 风格 schema：process.argv、systemd.lib、systemd.mainExecStart、systemd.service、systemd.services、systemd.sockets；提升后的单元由 NixOS 风格 attrs（wantedBy、serviceConfig等）翻译为 Home Manager 消费的 INI 结构（{ Unit; Service; Install; }）。
• 子服务（嵌套services.<sub>）以父服务名为前缀虚线命名；空单元键""表示服务主单元，process.argv成为其默认ExecStart。
• configData.<name>声明配置文件，物化到$XDG_CONFIG_HOME/home-services/<service>/<name>，其 store 路径自动加入主单元的X-Reload-Triggers，配置变化即触发服务重启；如需 reload 而非 restart，可覆盖X-SwitchMethod = "reload"。
• 包内模块若含DynamicUser、AmbientCapabilities等用户会话无法执行的指令，单元仍会生成（用户 systemd 静默忽略无法应用的指令），WantedBy=multi-user.target自动归一化为WantedBy=default.target，其余指令可按服务覆盖。

其他 Highlights 逐条解读

Podman 与 Rclone（Darwin 增强）

• services.podman.useDefaultMachine及 Darwin 上的 podman machine 管理选项新增（见 modules/services/podman 目录）。
• programs.rclone模块在 Darwin 上支持 launchd 托管的 config、mount、serve agent；新增programs.rclone.remotes.<name>.serve可在 Linux 与 Darwin 上管理rclone servesidecar 服务。非 systemd 平台下programs.rclone.requiresUnit为只读且恒为null。

Syncthing 凭据流程变更

services.syncthing.passwordFile已移除，改用services.syncthing.guiCredentials。若旧配置使用了密码文件，需迁移到新选项。

Firefox 扩展改为按 profile 管理

顶层programs.firefox.extensions = [ ... ]列表被移除，改为：

programs.firefox.profiles.myprofile.extensions.packages = [ pkgs.firefox-addons.xxx ]; programs.firefox.profiles.myprofile.extensions.settings."{extension-id}".permissions = [ ... ];

旧顶层写法需迁移到programs.firefox.profiles.<name>.extensions.packages。实现见 modules/programs/firefox/mkFirefoxModule.nix，extensions.packages会链接进profilesPath/<profile>/extensions（mkFirefoxModule.nix）。

Thunderbird 增强

新增accounts.email.accounts.<name>.ews、outlook.office365.com-ews账户 flavor、声明式语言包与 enterprise policies。使用outlook.office365.comflavor 且未显式设置认证方式的账户，IMAP/SMTP 认证默认改为 OAuth2。

systemd 用户单元包安装

新增systemd.user.packages，提供systemd.packages的用户级等价物，可直接从包中安装 unit 文件到用户目录。

WezTerm 声明式配置

新增programs.wezterm.settings（见 modules/programs/wezterm.nix）：

programs.wezterm.settings = { color_scheme = "Catppuccin Mocha"; font_size = 13; font = lib.generators.mkLuaInline ''wezterm.font("JetBrains Mono")''; };

• 设置以 Nix attrset 表达，经lib.generators.toLua序列化为$XDG_CONFIG_HOME/wezterm/wezterm.lua。
• lib.generators.mkLuaInline可内嵌wezterm.font、wezterm.action.*等原始 Lua 表达式。
• 既有programs.wezterm.extraConfig仍完全支持，可与settings组合；冲突时extraConfig返回的表优先（但为浅合并，见 modules/programs/wezterm.nix）。

Anki 选项修正与迁移

• programs.anki.uiScale取值修正为1.0–2.0（此前误为0.0–1.0）。
• 同步选项从programs.anki.sync.*移至programs.anki.profiles."User 1".sync.*；programs.anki.sync.passwordFile迁移为programs.anki.profiles."User 1".sync.keyFile。

VSCode 系分支独立模块化

为programs.cursor、programs.vscodium、programs.windsurf、programs.kiro、programs.antigravity新增专用模块，均由共享工厂mkVscodeModule构建，可独立且同时配置多个 fork。此前通过programs.vscode.package选择分支的写法需迁移到对应模块；programs.vscode.pname选项已移除。

AI 编码助手模块统一context

programs.claude-code、programs.codex、programs.opencode共享统一的context选项（提供全局指令）。旧的claude-code.memory、codex.custom-instructions、opencode.rules废弃并自动迁移。programs.mcp.servers通过新增的enableMcpIntegration扩展到更多助手与编辑器模块。

man 模块拆分

programs.man拆分为互斥的programs.man.man-db.enable与programs.man.mandoc.enable子模块，用于选择 man 查看器实现。

Neovim：initLua与 sideload

programs.neovim.extraLuaConfig更名为programs.neovim.initLua；默认将生成的 Lua 初始化写入$XDG_CONFIG_HOME/nvim/init.lua。若该文件由外部管理，需设置programs.neovim.sideloadInitLua = true，改由 Neovim wrapper 加载生成的 Lua。

sshAuthSock模块

新增sshAuthSock模块统一管理SSH_AUTH_SOCK环境变量，由提供 SSH agent 的模块（services.ssh-agent、services.gpg-agent等）隐式配置（见 modules/misc/ssh-auth-sock.nix）。旧的services.ssh-agent.enable{Bash,Zsh,Fish,Nushell}Integration选项已移除，shell 初始化统一走sshAuthSock。

PipeWire 客户端配置

新增services.pipewire.enable模块，提供 PipeWire、WirePlumber 与 PulseAudio/JACK 兼容层的客户端侧配置，不安装也不管理 PipeWire 守护进程本身。

swww → awww 重命名

services.swww随上游项目更名迁移为services.awww，enable、package、extraArgs自动迁移。

移除 freeformextraConfig逃生舱

• programs.aerospace.extraConfig（及userSettings）、programs.aria2.extraConfig移除，改用 RFC 42settings。
• programs.mise.settings更名为programs.mise.globalConfig.settings。
• programs.eww.configDir及enable{Bash,Zsh,Fish}Integration移除，改用programs.eww.yuckConfig与programs.eww.scssConfig声明式配置。
• programs.niriswitcher选项移除。

Darwin 集成行为变更

• launchd agent 启动前等待/nix/store挂载；替换 agent 时使用launchctl bootout --wait。
• nix-darwin activation 将 dry-run 模式传播到 Home Manager 用户激活。
• Home Manager 导出TERMINFO_DIRS，使 shell 可见 Home Manager 安装包提供的 terminfo 条目。

nix.assumeXdg与频道位置探测

新增nix.assumeXdg，适用于 Nix 在 Home Manager 之外配置了 XDG base directories 的安装；Home Manager 同时会检测osConfig.nix.settings.use-xdg-base-directories以决定声明式 channel 条目放置位置。

State Version 26.05 变更清单

以下变更仅在home.stateVersion = "26.05"（或更新）时生效：

升级建议

1. 先升级，后改 stateVersion：保持旧home.stateVersion运行一次home-manager switch，确认迁移警告（matchBlocks、extraConfig、firefox.extensions 等）按提示处理完毕，再将 stateVersion 提升为26.05。
2. 善用自动迁移：SSHmatchBlocks、AI 模块context、services.swww.*等均自动迁移，但自动迁移后建议手动改写为新写法，避免长期依赖废弃路径。
3. 关注破坏性移除：programs.firefox.extensions、programs.vscode.pname、services.syncthing.passwordFile、programs.aerospace.extraConfig等属于直接移除项，升级前务必完成迁移。
4. 按需启用新能力：home-manager.startAsUserService与home.services模块化服务均为新增能力，前者实验性较强，后者面向希望复用 nixpkgs 包内服务模块的用户，按实际场景决定是否启用。

完整的官方发布说明可随时查阅 docs/release-notes/rl-2605.md，模块化服务详细文档见 docs/manual/usage/modular-services.md。

【免费下载链接】home-managerManage a user environment using Nix [maintainer=@khaneliman, @rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager