Home Manager 发布说明全解读：版本演进、stateVersion 机制与配置迁移实战

Home Manager 发布说明全解读版本演进、stateVersion 机制与配置迁移实战【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-managerHome Manager 的发布说明Release Notes是理解这个 Nix 用户环境管理工具版本演进的核心资料它以docs/release-notes/release-notes.md为聚合入口按时间倒序收录从 18.09 到当前不稳定分支 26.11 的全部版本变更。本文以该文档为骨架逐层拆解 Highlights功能变更与 State Version Changes状态版本变更两大板块的含义并结合仓库源码与既有章节帮助读者在升级 Home Manager 时准确判断哪些变更会影响我的配置、何时生效、如何迁移。发布说明的整体结构一份倒序的版本编年史仓库根目录下的 docs/release-notes/release-notes.md 本身是一个章节聚合页正文只声明了发布说明的定位——列出 Home Manager 稳定版本与当前不稳定版本的发布说明——随后通过include机制按顺序引入全部版本章节rl-2611.md rl-2605.md rl-2511.md rl-2505.md rl-2411.md rl-2405.md rl-2311.md rl-2305.md rl-2211.md rl-2205.md rl-2111.md rl-2105.md rl-2009.md rl-2003.md rl-1909.md rl-1903.md rl-1809.md每一个rl-XXXX.md文件例如 docs/release-notes/rl-2611.md、docs/release-notes/rl-2505.md对应一个以年月命名的发布分支且内部结构高度统一几乎都包含两个固定板块Highlights该版本引入的功能、模块、命令行行为变化State Version Changes仅在home.stateVersion设置为该版本号或更新时才生效的行为变化。这种两部分结构意味着不是所有变更都会自动作用到你的配置上。Highlights 中的破坏性变更通常立即生效或者通过 deprecation 警告过渡而 State Version Changes 则被home.stateVersion这个开关门控用于在新旧行为之间做兼容切换。先理解home.stateVersion贯穿所有版本的门控机制要读懂任何一份 Home Manager 发布说明必须先理解home.stateVersion选项。从 docs/release-notes/rl-2211.md 可以看到它的来历该选项最初由 18.09 版本引入此前一直有默认值18.09从 22.11 起不再提供默认值如果配置中没有显式设置需要手动补上home.stateVersion 18.09;而在 docs/release-notes/rl-2009.md 中home.homeDirectory与home.username也从读取HOME/USER环境变量改为必须显式配置进一步强化了配置的声明性与可复现性。home.stateVersion的语义是它记录的是这份配置最初是为哪个版本编写的而不是当前运行的 Home Manager 版本。每次发布说明中的 State Version Changes 小节都会强调These changes are only active if thehome.stateVersionoption is set to 26.05 or later.也就是说当你把home.stateVersion从24.11提升到26.05时24.11→26.05 之间累积的所有 State Version Changes 才会同时生效。发布说明正是你决定是否升级 stateVersion、升级后需要调整哪些配置的依据清单。模块实现侧这类按版本分流的逻辑集中在 modules/misc/version.nix 等基础模块中由 Home Manager 在评估配置时读取并分发。当前不稳定分支 26.11聚焦声明式配置收敛docs/release-notes/rl-2611.md 标注为当前不稳定分支信息尚未最终确定但仍能看出 Home Manager 的演进方向。26.11 的 Highlights 集中在四件事1. uv 模块升级为完整的 Python 工具链管理器。新的programs.uv.python.versions、programs.uv.python.default与programs.uv.tool.packages选项可以安装由 uv 管理的 Python 版本与工具未固定unpinned的条目会在每次 activation 时跟踪最新发布固定的条目保持不动配合programs.uv.python.prune/programs.uv.tool.prune可以删除不再列出的版本与工具让托管集合完全声明式。2. Darwin 上 launchd agent 的 domain 选择。launchd.agents.name.domain允许在用户的 GUI 域与后台域之间选择默认使用 GUI 域需要在没有图形登录会话时运行的服务应显式设为user。对应的类型定义位于 modules/launchd/types.nix。3. 服务启动时序修复。services.voxtype守护进程改为随graphical-session.target启动此前是default.target确保在合成器持有 GPU render node 之后再启动从而让 Vulkan 加速的 whisper 构建能正确探测设备而不是回退到 CPU。4. 自由格式配置向settings收敛。XSuspender 改用services.xsuspender.settings承载自由格式 INI 配置旧选项services.xsuspender.defaults迁入settings.Defaultservices.xsuspender.rules迁入settings.name键名改为 snake_case如suspend_delay替代suspendDelay。同样地TWMN 改用services.twmn.settings原生选项与extraConfig值都合并进settings启用服务但完全不配置时不再生成配置文件。这是 Home Manager 持续推进的extraConfig→ RFC 42 风格settings路线的一部分。26.11 的 State Version Changes 还包含两个值得注意的细节Darwin 上programs.firefox.configPath默认值改为Library/Application Support/org.nixos.firefox迁移前需先退出 Firefox 并移动数据programs.zellij的 KDL 生成器修复了字符串中的反斜杠与制表符转义——例如 Nix 字符串\\现在能正确生成 KDL 字符串\\而不是非法的\。26.05 稳定版模块体系大扩军docs/release-notes/rl-2605.md 是最近一个稳定分支亮点密度很高SSH 配置走向 RFC 42新增programs.ssh.settings旧的programs.ssh.matchBlocks格式被弃用并自动迁移启动方式更灵活新选项home-manager.startAsUserService把用户 activation 推迟到登录时按需执行适合家目录较晚挂载如 pam_mount的系统home.services命名空间支持把 nixpkgs 的 modular services如pkgs.name.passthru.services.default原样提升为用户 systemd unit细节见 docs/usage/modular-services.mdFirefox 扩展改为 per-profile 管理顶层programs.firefox.extensions [ ... ]被移除迁入programs.firefox.profiles.name.extensions.packagesVSCode fork 独立成模块programs.cursor、programs.vscodium、programs.windsurf、programs.kiro、programs.antigravity由共享的mkVscodeModule工厂生成可独立且同时配置programs.vscode.pname被移除AI 编程助手模块统一 contextprograms.claude-code、programs.codex、programs.opencode共用context选项提供全局指令旧的claude-code.memory、codex.custom-instructions、opencode.rules自动迁移MCP 配置通过enableMcpIntegration扩展到更多模块WezTerm 声明式配置新增programs.wezterm.settingsNix 属性集经lib.generators.toLua序列化为 Lua可通过lib.generators.mkLuaInline内嵌wezterm.font、wezterm.action.*等原生 Lua 表达式且与现有extraConfig可组合使用sshAuthSock模块统一管理SSH_AUTH_SOCK环境变量取代各 SSH-agent 模块的enable{Bash,Zsh,Fish,Nushell}Integration选项PipeWire 客户端配置新增services.pipewire模块只配置客户端侧不管理守护进程本身services.swww随上游更名迁至services.awww。26.05 的 State Version Changes 同样影响面广gtk.gtk4.theme不再默认镜像gtk.themeprograms.zsh.dotDir在启用 XDG 时默认~/.config/zshprograms.yazi.shellWrapperName默认从yy改为yxdg.userDirs.setSessionVariables默认改为falsexdg.userDirs.extraConfig不再接受XDG_name_DIR形式键名Hyprland 的configType默认改为luaservices.home-manager.autoUpgrade.preSwitchCommands默认改为空列表需要每次自动切换前更新 flake 输入时显式设回[ nix flake update ]。25.11 与 25.05命令行与激活机制的关键变化25.11switch 命令迎来 rollback 与 specialisationdocs/release-notes/rl-2511.md 引入了两个直接对标nixos-rebuild的命令行能力home-manager switch --rollback激活当前世代之前的一个 Home Manager 世代。以往手动激活旧世代总会新建 profile generation新行为与nixos-rebuild switch --rollback一致详见 docs/usage/rollbacks.mdhome-manager switch --specialisation NAME激活指定名称的 specialisation对应nixos-rebuild switch --specialisation免去手动执行 specialisation activate 脚本的繁琐相关模块见 modules/misc/specialisation.nix。25.11 还调整了 profile 管理模型更新 Home Manager Nix profile 不再默认发生在 activation 脚本内部而改由调用方如home-manager工具负责旧行为仅为向后兼容保留自定义工具调用 activation 脚本的方式见 docs/internals/activation.md。作为 NixOS / nix-darwin 模块使用时不再为每个用户创建多余的 shadow profile可显式用home-manager.enableLegacyProfileManagement true;恢复。另外新增home-manager.minimal选项只导入基础模块、按需手动imports其余模块如${modulesPath}/programs/fzf.nix以缩短求值时间适合熟悉模块体系的进阶用户。25.05systemd 服务重启语义与测试套件调整docs/release-notes/rl-2505.md 中systemd.user.startServices默认值改为trueactivation 时自动按需重启服务legacy取值被移除使用会直接求值报错suggest保留但可能在未来弃用。此外 Home Manager 的主测试套件从主 flake 中移出改为通过 tests 目录下的独立 flake 提供运行示例见 docs/contributing/tests.md。State Version Changes 方面programs.git.signing.format不再默认openpgp使用 GPG 签名的用户需显式设置以维持旧行为。24.x 与 23.xAPI 清理与安装体验改进24.11docs/release-notes/rl-2411.mdswayidle 的-w标志从硬编码移入services.swayidle.extraArgs默认值自行设置过该选项的用户需手动补-wprograms.eza.icons的布尔值用法被弃用true改为auto、false改为null。本版本无 State Version Changes。24.05docs/release-notes/rl-2405.mdhome-manager uninstall被重构新增布尔选项uninstall可在纯 Flake 安装中通过uninstall true;构建并激活来实现清理。需要强调的是激活该配置会移除所有Home Manager 管理文件与历史世代操作前务必谨慎。同时activation 脚本 API 开始现代化$DRY_RUN_CMD、$DRY_RUN_NULL被 shell 函数run取代$VERBOSE_ECHO被verboseEcho取代# 迁移前 home.activation.reportChanges config.lib.dag.entryAnywhere if [[ -v oldGenPath ]]; then $DRY_RUN_CMD nix store diff-closures $oldGenPath $newGenPath fi ; # 迁移后 home.activation.reportChanges config.lib.dag.entryAnywhere if [[ -v oldGenPath ]]; then run nix store diff-closures $oldGenPath $newGenPath fi ;23.11docs/release-notes/rl-2311.mdfish 的home.sessionVariables转译改用 babelfish显著加快 shell 启动.release文件由信息更丰富的release.json仓库根目录 release.json取代选项文档迁移到上游 Nixpkgs 的lib.nixosOptionsDoc处理器外部模块的选项描述需改用 Nixpkgs 风格 Markdownservices.password-store-sync模块移除改用services.git-sync。23.05docs/release-notes/rl-2305.mdFirefox 扩展改为 per-profile 管理programs.firefox.profiles.myprofile.extensions默认配置位置从~/.config/nixpkgs/home.nix迁至~/.config/home-manager/home.nixflake 同理旧位置会触发警告home-manager工具新增init命令用于生成并可选激活初始配置Flake 独立安装推荐走此路径详见 docs/nix-flakes/standalone.md。State Version Changes 包括 i3/sway 窗口标题栏选项默认改为true、programs.swaylock.enable默认改为false必须显式启用。22.xFlake 接口定型与激活可复现性22.11docs/release-notes/rl-2211.md是 Flake 用户必须关注的一个版本homeManagerConfiguration函数被大幅简化移除了configuration、username、homeDirectory、stateVersion、extraModules、system参数统一改用modules列表参数且pkgs变为必填# 迁移前 homeManagerConfiguration { configuration import ./home.nix; system x86_64-linux; username jdoe; homeDirectory /home/jdoe; stateVersion 22.05; extraModules [ ./some-extra-module.nix ]; } # 迁移后 homeManagerConfiguration { pkgs nixpkgs.legacyPackages.${system}; modules [ ./home.nix ./some-extra-module.nix { home { username jdoe; homeDirectory /home/jdoe; stateVersion 22.05; }; } ]; }同期services.picom重构为结构化 settingsextraOptions、blur*移除services.compton模块20.03 起弃用被删除。State Version Changes 中最重要的一条是activation 脚本在执行前重置PATH只允许显式指定的命令需要运行自定义命令时应使用绝对路径如${pkgs.hello}/bin/hello以提升可复现性。22.05docs/release-notes/rl-2205.mdprograms.waybar.settings.modules被移除waybar 模块直接声明在programs.waybar.settings下开始部分支持多语言翻译仅覆盖 Bash 部分如home-manager命令行工具与 activation 脚本新增launchd.agents模块支持 macOS LaunchAgents。21.x 与 20.xsettings 化与平台策略的历史转折21.11docs/release-notes/rl-2111.md做出一个影响深远的决定所有模块在所有平台上加载。此前平台相关模块只在对应平台加载虽然省求值时间但导致文档缺项、跨平台共享配置受限详见 issue #1906 的讨论。此后启用不兼容平台的模块会得到更清晰的错误提示。同期 Rofi 1.7.0 的选项迁移到programs.rofi.themeTaskwarrior 配置文件位置改为$XDG_CONFIG_HOME/task/taskrc。State Version Changes 包括home.keyboard默认改为null不再自动管理键盘布局X 会话中不再运行setxkbmap等。21.05docs/release-notes/rl-2105.md展示了大批选项从字符串/属性集向结构化类型迁移的典型范例programs.broot.verbs从 attrset 改为 list键移入每项的invocationprograms.mpv.package支持自定义 derivation并新增programs.mpv.finalPackage指向最终包装结果programs.mpv.package (pkgs.wrapMpv (pkgs.mpv-unwrapped.override { vapoursynthSupport true; }) { extraMakeWrapperArgs [ --prefix LD_LIBRARY_PATH : ${pkgs.vapoursynth-mvtools}/lib/vapoursynth ]; });programs.rofi.extraConfig从字符串改为属性集键去掉rofi.前缀programs.rofi.theme支持用属性集配合config.lib.formats.rasi.mkLiteral定义主题services.redshift.extraOptions/services.gammastep.extraOptions移除改用结构化settingsprograms.neovim.configure弃用改为programs.neovim.plugins与programs.neovim.extraConfigHome Manager 开始遵循NO_COLOR环境变量Qt 模块新增qt.style.name/qt.style.packagefontType库类型新增size属性programs.htop.settings取代programs.htop下的零散选项。20.09docs/release-notes/rl-2009.mdhome.homeDirectory、home.username必须有显式值xdg.cacheHome、xdg.configHome、xdg.dataHome不再受XDG_*环境变量影响无条件默认到~/.cache、~/.config、~/.local/sharenixpkgs模块不再引用nixpkgspkgs参数改由初始化 Home Manager 模块的同一份 Nixpkgs 构建纯 Flake 场景下的关键改进想保留旧行为可设置_module.args.pkgsPath nixpkgs;。更早的 20.03、19.09、19.03、18.09 章节docs/release-notes/rl-2003.md 及更早同样遵循 Highlights State Version Changes 的结构记录了该项目早期的配置格式定型过程。从发布说明看 Home Manager 的演进主线把 18.09 到 26.11 的章节串联起来可以清晰看到四条贯穿始终的演进主线extraConfig→settingsRFC 42 结构化配置从 20.09 的 redshift、21.05 的 htop/rofi、22.11 的 picom到 26.05 的 aerospace/aria2/ssh、26.11 的 xsuspender/twmn自由格式字符串配置持续被类型化的settings属性集取代配合 deprecation 警告与自动迁移平滑过渡Flake 成为一等公民22.11 的homeManagerConfiguration简化、23.05 的init命令、24.05 的 Flake 可用的uninstall选项、26.05 的startAsUserService逐步让基于 Nix Flake 的独立安装成为推荐路径平台支持收敛Linux systemd 与 Darwin launchd21.11 起所有模块全平台加载launchd agent 支持持续增强22.05 引入、26.11 的 domain 选择、26.05 的/nix/store等待与TERMINFO_DIRS导出macOS 上copyApps取代linkApps以兼容 Spotlight25.11激活与世代管理更可靠activation 脚本重置PATH22.11、run/verboseEcho替代旧变量24.05、profile 更新职责外移25.11、--rollback与--specialisation25.11。升级实践如何用发布说明指导一次配置迁移结合上述内容一次稳妥的 Home Manager 升级可以按四步走先读目标版本及其间的全部章节从 docs/release-notes/release-notes.md 的包含列表入手通读你要跨过的每个rl-XXXX.md的 Highlights找出标记为 removed、deprecated、与你的配置直接相关的条目区分立即生效与 stateVersion 门控Highlights 中的破坏性变更如选项移除、模块更名升级后即生效需要在升级前迁移State Version Changes 只有在把home.stateVersion提到对应版本后才生效可以选择推迟但要注意 22.11 起该选项没有默认值home.username/home.homeDirectory自 20.09 起必须显式设置善用自动迁移与警告大量选项迁移如programs.ssh.settings、Firefox per-profile extensions、context统一、settings化都带自动迁移与 deprecation 警告执行home-manager switch时留意输出涉及数据移动的如 Darwin 上 Firefox 的configPath变更要先备份并手工迁移数据必要时使用回滚与卸载能力升级异常时可用home-manager switch --rollback回到前一世代或通过--specialisation NAME切换到特定配置确需彻底清理时在 Flake 配置中设置uninstall true;构建激活会删除全部 Home Manager 状态与世代务必谨慎。结语Home Manager 的发布说明不只是变更清单它同时是配置迁移手册、状态版本机制的使用文档和项目演进史的浓缩。以 docs/release-notes/release-notes.md 为入口按版本逐章阅读配合home.stateVersion理解生效边界就能在每次升级中做到心中有数——知道哪些行为会变、为什么变、以及如何用最小代价完成迁移。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考