Home Manager 26.05 版本发布全览SSH RFC 42、按需激活、模块化服务与关键变更迁移指南【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-managerHome Manager 26.05 稳定版发布于 2026 年 5 月是该项目一次覆盖面极广的里程碑式发布。本指南以 docs/release-notes/rl-2605.md 为骨架逐条解读本次发布的 Highlights 与 State Version 变更并结合仓库源码说明新选项的底层实现、迁移路径与配置示例帮助你在升级到home.stateVersion 26.05时顺利完成配置迁移。RFC 42 风格的 SSH 配置programs.ssh.settings26.05 起Home Manager 支持以 RFC 42 风格声明式配置 OpenSSHprograms.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 homeDirectorynixos/default.nix。开启时生成统一的用户级服务systemd.user.services.home-manager通过 drop-in10-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.serviceExecStart指向 mpd 二进制默认WantedBydefault.target。关键语义每个服务暴露上游 NixOS 风格 schemaprocess.argv、systemd.lib、systemd.mainExecStart、systemd.service、systemd.services、systemd.sockets提升后的单元由 NixOS 风格 attrswantedBy、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 静默忽略无法应用的指令WantedBymulti-user.target自动归一化为WantedBydefault.target其余指令可按服务覆盖。其他 Highlights 逐条解读Podman 与 RcloneDarwin 增强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.nixextensions.packages会链接进profilesPath/profile/extensionsmkFirefoxModule.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.nixprograms.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 编码助手模块统一contextprograms.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 查看器实现。NeoviminitLua与 sideloadprograms.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.awwwenable、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或更新时生效选项变更内容gtk.gtk4.theme不再默认镜像gtk.themeprograms.zsh.dotDir当xdg.enable为 true 时默认值为 XDG 配置目录通常~/.config/zshprograms.yazi.shellWrapperName默认值由yy改为yxdg.userDirs.setSessionVariables默认值由true改为falsexdg.userDirs.extraConfig不再接受XDG_name_DIR形式的键直接使用名称如DESKTOP使用旧形式会触发警告programs.man.packageDarwin 上默认nullnixpkgs 的 GNU man 自带在 Darwin 上不可用的apropos/man -k与whatis/man -fNix 安装的 man 手册仍可通过 macOS 自带man配合home.extraOutputsToInstall使用programs.neovim.withPython3/withRuby默认false跟随 nixpkgsprograms.neovim.plugins.name.type默认lua此前为viml插件config片段默认按 Lua 处理programs.firefox.configPathLinux 上默认${config.xdg.configHome}/mozilla/firefox此前为~/.mozilla/firefoxwayland.windowManager.hyprland.configType默认lua此前为hyprlang如需继续生成$XDG_CONFIG_HOME/hypr/hyprland.conf显式设为hyprlangprograms.docker-cli.configDirxdg.enable为 true 时默认${config.xdg.configHome}/docker此前~/.dockerservices.colima.profiles为默认 context 设置$DOCKER_HOSTservices.home-manager.autoUpgrade.preSwitchCommands默认空列表此前useFlake true时默认[ nix flake update ]如需保持自动更新 flake inputs显式设置preSwitchCommands [ nix flake update ]programs.mergiraf.enableGitIntegration/enableJujutsuIntegration默认false集成需显式启用升级建议先升级后改 stateVersion保持旧home.stateVersion运行一次home-manager switch确认迁移警告matchBlocks、extraConfig、firefox.extensions 等按提示处理完毕再将 stateVersion 提升为26.05。善用自动迁移SSHmatchBlocks、AI 模块context、services.swww.*等均自动迁移但自动迁移后建议手动改写为新写法避免长期依赖废弃路径。关注破坏性移除programs.firefox.extensions、programs.vscode.pname、services.syncthing.passwordFile、programs.aerospace.extraConfig等属于直接移除项升级前务必完成迁移。按需启用新能力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 [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Manager 26.05 版本发布全览：SSH RFC 42、按需激活、模块化服务与关键变更迁移指南
Home Manager 26.05 版本发布全览SSH RFC 42、按需激活、模块化服务与关键变更迁移指南【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-managerHome Manager 26.05 稳定版发布于 2026 年 5 月是该项目一次覆盖面极广的里程碑式发布。本指南以 docs/release-notes/rl-2605.md 为骨架逐条解读本次发布的 Highlights 与 State Version 变更并结合仓库源码说明新选项的底层实现、迁移路径与配置示例帮助你在升级到home.stateVersion 26.05时顺利完成配置迁移。RFC 42 风格的 SSH 配置programs.ssh.settings26.05 起Home Manager 支持以 RFC 42 风格声明式配置 OpenSSHprograms.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 homeDirectorynixos/default.nix。开启时生成统一的用户级服务systemd.user.services.home-manager通过 drop-in10-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.serviceExecStart指向 mpd 二进制默认WantedBydefault.target。关键语义每个服务暴露上游 NixOS 风格 schemaprocess.argv、systemd.lib、systemd.mainExecStart、systemd.service、systemd.services、systemd.sockets提升后的单元由 NixOS 风格 attrswantedBy、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 静默忽略无法应用的指令WantedBymulti-user.target自动归一化为WantedBydefault.target其余指令可按服务覆盖。其他 Highlights 逐条解读Podman 与 RcloneDarwin 增强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.nixextensions.packages会链接进profilesPath/profile/extensionsmkFirefoxModule.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.nixprograms.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 编码助手模块统一contextprograms.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 查看器实现。NeoviminitLua与 sideloadprograms.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.awwwenable、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或更新时生效选项变更内容gtk.gtk4.theme不再默认镜像gtk.themeprograms.zsh.dotDir当xdg.enable为 true 时默认值为 XDG 配置目录通常~/.config/zshprograms.yazi.shellWrapperName默认值由yy改为yxdg.userDirs.setSessionVariables默认值由true改为falsexdg.userDirs.extraConfig不再接受XDG_name_DIR形式的键直接使用名称如DESKTOP使用旧形式会触发警告programs.man.packageDarwin 上默认nullnixpkgs 的 GNU man 自带在 Darwin 上不可用的apropos/man -k与whatis/man -fNix 安装的 man 手册仍可通过 macOS 自带man配合home.extraOutputsToInstall使用programs.neovim.withPython3/withRuby默认false跟随 nixpkgsprograms.neovim.plugins.name.type默认lua此前为viml插件config片段默认按 Lua 处理programs.firefox.configPathLinux 上默认${config.xdg.configHome}/mozilla/firefox此前为~/.mozilla/firefoxwayland.windowManager.hyprland.configType默认lua此前为hyprlang如需继续生成$XDG_CONFIG_HOME/hypr/hyprland.conf显式设为hyprlangprograms.docker-cli.configDirxdg.enable为 true 时默认${config.xdg.configHome}/docker此前~/.dockerservices.colima.profiles为默认 context 设置$DOCKER_HOSTservices.home-manager.autoUpgrade.preSwitchCommands默认空列表此前useFlake true时默认[ nix flake update ]如需保持自动更新 flake inputs显式设置preSwitchCommands [ nix flake update ]programs.mergiraf.enableGitIntegration/enableJujutsuIntegration默认false集成需显式启用升级建议先升级后改 stateVersion保持旧home.stateVersion运行一次home-manager switch确认迁移警告matchBlocks、extraConfig、firefox.extensions 等按提示处理完毕再将 stateVersion 提升为26.05。善用自动迁移SSHmatchBlocks、AI 模块context、services.swww.*等均自动迁移但自动迁移后建议手动改写为新写法避免长期依赖废弃路径。关注破坏性移除programs.firefox.extensions、programs.vscode.pname、services.syncthing.passwordFile、programs.aerospace.extraConfig等属于直接移除项升级前务必完成迁移。按需启用新能力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 [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考