Home Manager 20.09 版本发布解读stateVersion 机制、路径确定性化与窗口管理器配置迁移实战【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager本文基于 Home Manager 官方发布说明 rl-2009.md 整理系统解读 20.09 稳定分支2020 年 9 月底发布引入的 State Version状态版本行为变更。读者将掌握home.stateVersion 20.09后home.homeDirectory、XDG 基础目录、Git SMTP 加密、nixpkgs模块与 sway/i3 状态栏等配置的迁移要点并能在升级时避免常见的路径与环境变量回退问题。20.09 版本背景与发布说明定位20.09 是 Home Manager 早期的一个稳定分支版本其发布说明的特殊之处在于亮点Highlights部分明确写着 Nothing has happened.即该版本没有引入新的功能亮点核心变化全部集中在 State Version 语义调整上。这一事实也提醒我们State Version 变更往往比功能新增更能影响存量配置的可移植性升级时优先关注发布说明中的状态版本小节是正确做法。从源码看State Version 的本质是一组按版本号触发的条件分支。例如 home-environment.nix 中home.username lib.mkIf (lib.versionOlder config.home.stateVersion 20.09) ( lib.mkDefault (builtins.getEnv USER) ); home.homeDirectory lib.mkIf (lib.versionOlder config.home.stateVersion 20.09) ( lib.mkDefault (builtins.getEnv HOME) );lib.versionOlder config.home.stateVersion 20.09表示当前状态版本早于 20.09时才生效这正是变更仅在home.stateVersion设为20.09或更高时激活的源码级印证。同理20.09 引入的所有行为变化都可以在当前仓库中通过搜索versionOlder/versionAtLeast与20.09的组合找到对应实现。home.homeDirectory 与 home.username 不再提供默认值20.09 起home.homeDirectory和home.username两个选项取消默认值必须在配置中显式提供。此前它们的默认值分别来自环境变量HOME与USER这带来两个问题配置的求值结果依赖外部环境同样的配置在不同 shell 环境下可能生成不同路径破坏可复现性在 Nix Flake 等纯净求值上下文中builtins.getEnv的结果不稳定容易产生难以排查的路径漂移。对应选项定义位于 home-environment.nixhome.homeDirectory mkOption { type types.path; defaultText lib.literalMD $HOME, for state version 20.09 undefined, otherwise. ; apply toString; example /home/jane.doe; description The users home directory. Must be an absolute path. If Home Manager is installed as a NixOS or nix-darwin submodule, it is set to osConfig.users.users.name.home. ; };升级到 20.09 后最小配置必须至少包含{ config, pkgs, ... }: { home.username jane; home.homeDirectory /home/jane; home.stateVersion 20.09; }如果 Home Manager 以 NixOS 或 nix-darwin 子模块方式安装这两个选项会自动继承osConfig.users.users.name.home与同名用户名无需手工填写。XDG 基础目录默认值的确定性化与上述变更配套20.09 起xdg.cacheHome、xdg.configHome、xdg.dataHome以及xdg.binHome、xdg.stateHome不再读取XDG_CACHE_HOME、XDG_CONFIG_HOME、XDG_DATA_HOME等环境变量而是无条件默认到选项20.09 起的新默认值xdg.cacheHome${config.home.homeDirectory}/.cachexdg.configHome${config.home.homeDirectory}/.configxdg.dataHome${config.home.homeDirectory}/.local/sharexdg.binHome${config.home.homeDirectory}/.local/binxdg.stateHome${config.home.homeDirectory}/.local/state这一现代确定性分支在 modules/misc/xdg/default.nix 中实现# Modern deterministic setup. (mkIf (!cfg.enable lib.versionAtLeast config.home.stateVersion 20.09) { xdg.cacheHome mkOptionDefault defaultCacheHome; xdg.configHome mkOptionDefault defaultConfigHome; xdg.dataHome mkOptionDefault defaultDataHome; xdg.binHome mkOptionDefault defaultBinHome; xdg.stateHome mkOptionDefault defaultStateHome; })而 20.09 之前是传统非确定性分支会优先取环境变量、环境变量为空时才回退到默认值default.nix 中的getEnvFallback逻辑。因此如果你从未自定义过 XDG 基础目录升级无感默认路径保持不变如果你依赖XDG_CONFIG_HOME等环境变量指向非默认路径切到 20.09 后必须显式设置对应选项否则文件会被链接到默认路径下。对应行为有测试覆盖见 tests/modules/misc/xdg/default-locations.nix该测试在xdg.enable false、home.stateVersion 20.09的前提下断言xdg.configFile等文件被精确链接到.config、.local/share、.cache、.local/state四个默认位置证明 20.09 之后的求值结果与环境变量无关、完全确定。需要特别说明的是本仓库当前版本的 modules/misc/xdg/default.nix 中当xdg.enable true时XDG_CACHE_HOME等会话变量会在home.sessionVariables与systemd.user.sessionVariables中统一导出即便关闭xdg.enable20.09 分支也会让各*Home选项指向上述确定性默认值两条路径都不会再读外部环境变量。升级工具链的自动适配发布说明指出通过如下命令生成初始配置时若有必要会自动补上这些选项$ nix-shell home-manager -A install也就是说新用户通过安装脚本引导生成home.nix时20.09 及以后版本的模板会把home.username、home.homeDirectory、home.stateVersion以及必要的 XDG 路径选项一并写入避免改完状态版本后配置突然失效的坑。存量用户升级时建议对照上述表格逐一检查自己是否显式设置了 XDG 相关选项。Git sendemail 的 smtpEncryption 语义修正20.09 起accounts.email账号生成 Gitsendemail配置时smtpEncryption的取值逻辑被收紧仅当smtp.tls.enable true且smtp.tls.useStartTls true时才生成tls仅当smtp.tls.enable true而useStartTls未开启或为false时生成ssl两者皆不满足时为空字符串。对应实现位于 modules/programs/git.nixsmtpEncryption if smtp.tls.enable then (if smtp.tls.useStartTls || lib.versionOlder config.home.stateVersion 20.09 then tls else ssl) else ;注意其中的兼容分支lib.versionOlder config.home.stateVersion 20.09表示旧版本下只要开启 TLS 就一律用tls只有状态版本 ≥ 20.09 时才根据是否启用 STARTTLS 区分tls与ssl。这是典型的按状态版本拆分新旧语义的实现模式也说明同一份配置在不同stateVersion下可能生成不同的 Git 配置内容。相关行为由测试 tests/modules/programs/git/git-with-email.nixhome.stateVersion 20.09及配套的git-with-email-expected.conf期望文件验证。nixpkgs 模块不再引用nixpkgs20.09 之前构建pkgs模块参数时会隐式引用nixpkgs通道20.09 起pkgs改为从初始化 Home Manager 模块时所用的同一份 Nixpkgs构建。这对使用 Nix Flake 的场景尤其重要——此前 Flake 用户可能在无意中混合了两份不同的 Nixpkgs造成版本错配。源码依据见 modules/misc/nixpkgs.nix_pkgs import pkgsPath (lib.filterAttrs (_n: v: v ! null) config.nixpkgs);pkgsPath从_module.args注入同文件 L141 附近的_module.args { ... }其值在状态版本 ≥ 20.09 时默认指向初始化 Home Manager 所用的 Nixpkgs而非nixpkgs通道。如果你确实希望继续使用nixpkgs通道发布说明给出了显式声明方式_module.args.pkgsPath nixpkgs;将其加入 Home Manager 配置即可恢复旧行为。需要提示的是Home Manager 与 Nixpkgs 版本不匹配可能引发告警home-environment.nix 中的 release 检查因此保持两份 Nixpkgs 版本一致通常是更稳妥的选择。sway 与 i3 的 bars 选项改为可空nullable20.09 对wayland.windowManager.sway.config.bars与xsession.windowManager.i3.config.bars做了结构性调整大部分子选项变为null可空默认值统一为null同时为整个bars选项手工设置了一套旧默认值。这一设计的实现集中在共享选项模块 modules/services/window-managers/i3-sway/lib/options.nixmkNullableOption { type, default, ... }args: mkOption ( args // { type types.nullOr type; default if versionAtLeast2009 then null else default; defaultText literalExpression null for state version ≥ 20.09, as example otherwise ; } );而bars本身的默认值在 options.nix 中按状态版本区分bars mkOption { type types.listOf barModule; default if lib.versionAtLeast stateVersion 20.09 then [ { mode dock; hiddenState hide; position bottom; workspaceButtons true; workspaceNumbers true; statusCommand ${pkgs.i3status}/bin/i3status; fonts { names [ monospace ]; size 8.0; }; trayOutput primary; colors { /* 与旧版完全一致的配色默认值 */ }; } ] else [ { } ]; ... };整体效果是不设置bars时行为完全不变但只要显式写了bars未指定的子选项不再被旧默认值填满而是保持null生成配置时该行直接省略。发布说明给出的例子bars [ { command waybar; } ];20.09 之前会生成一段被旧默认值字体、模式、位置、i3status状态命令、workspace 按钮、tray、全套配色等填满的bar { ... }配置块20.09 之后只生成bar { swaybar_command waybar }command选项与生成逻辑的对应关系见 sway.nixcommand默认值为${pkg}/bin/${moduleName}bar生成时通过barStr渲染为swaybar_command/status_command等行。这意味着20.09 之后bars更像是增量声明你只写关心的字段其余交给 i3/sway 自身默认值若你此前依赖写一个command就自动附带全套 i3status 默认配置的旧行为升级后需要自行补齐statusCommand、colors等字段或直接不设置bars保持默认。升级到 20.09 的迁移检查清单综合发布说明与源码从旧状态版本切到home.stateVersion 20.09时建议依次核对必填项home.username与home.homeDirectory已在配置中显式给出XDG 路径若曾依赖XDG_CACHE_HOME/XDG_CONFIG_HOME/XDG_DATA_HOME等环境变量指向自定义路径需显式设置xdg.cacheHome/xdg.configHome/xdg.dataHome及xdg.binHome/xdg.stateHomeGit 邮件账号确认accounts.email.accounts.name.smtp.tls.enable与useStartTls的组合是否符合预期的tls/ssl取值Nixpkgs 来源确认pkgs是否应继续使用nixpkgs通道必要时添加_module.args.pkgsPath nixpkgs;sway/i3 状态栏检查bars是否显式设置、未指定字段是否会因null而被省略必要时补齐statusCommand、colors等。小结20.09 是 Home Manager 在可复现性方向上的一次集中收敛取消home.homeDirectory/home.username的环境变量默认值、将 XDG 基础目录改为确定性默认、让pkgs与初始化所用的 Nixpkgs 保持一致本质上都是在消除求值结果对外部环境与通道状态的隐式依赖。bars选项的 nullable 化则体现了另一条原则——选项默认值应当尽量由上游工具负责Home Manager 只做显式声明。理解这些变更背后的状态版本分支机制lib.versionOlder/versionAtLeast与20.09的组合也就掌握了阅读后续所有发布说明中 State Version Changes 的通用方法。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Home Manager 20.09 版本发布解读：stateVersion 机制、路径确定性化与窗口管理器配置迁移实战
Home Manager 20.09 版本发布解读stateVersion 机制、路径确定性化与窗口管理器配置迁移实战【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager本文基于 Home Manager 官方发布说明 rl-2009.md 整理系统解读 20.09 稳定分支2020 年 9 月底发布引入的 State Version状态版本行为变更。读者将掌握home.stateVersion 20.09后home.homeDirectory、XDG 基础目录、Git SMTP 加密、nixpkgs模块与 sway/i3 状态栏等配置的迁移要点并能在升级时避免常见的路径与环境变量回退问题。20.09 版本背景与发布说明定位20.09 是 Home Manager 早期的一个稳定分支版本其发布说明的特殊之处在于亮点Highlights部分明确写着 Nothing has happened.即该版本没有引入新的功能亮点核心变化全部集中在 State Version 语义调整上。这一事实也提醒我们State Version 变更往往比功能新增更能影响存量配置的可移植性升级时优先关注发布说明中的状态版本小节是正确做法。从源码看State Version 的本质是一组按版本号触发的条件分支。例如 home-environment.nix 中home.username lib.mkIf (lib.versionOlder config.home.stateVersion 20.09) ( lib.mkDefault (builtins.getEnv USER) ); home.homeDirectory lib.mkIf (lib.versionOlder config.home.stateVersion 20.09) ( lib.mkDefault (builtins.getEnv HOME) );lib.versionOlder config.home.stateVersion 20.09表示当前状态版本早于 20.09时才生效这正是变更仅在home.stateVersion设为20.09或更高时激活的源码级印证。同理20.09 引入的所有行为变化都可以在当前仓库中通过搜索versionOlder/versionAtLeast与20.09的组合找到对应实现。home.homeDirectory 与 home.username 不再提供默认值20.09 起home.homeDirectory和home.username两个选项取消默认值必须在配置中显式提供。此前它们的默认值分别来自环境变量HOME与USER这带来两个问题配置的求值结果依赖外部环境同样的配置在不同 shell 环境下可能生成不同路径破坏可复现性在 Nix Flake 等纯净求值上下文中builtins.getEnv的结果不稳定容易产生难以排查的路径漂移。对应选项定义位于 home-environment.nixhome.homeDirectory mkOption { type types.path; defaultText lib.literalMD $HOME, for state version 20.09 undefined, otherwise. ; apply toString; example /home/jane.doe; description The users home directory. Must be an absolute path. If Home Manager is installed as a NixOS or nix-darwin submodule, it is set to osConfig.users.users.name.home. ; };升级到 20.09 后最小配置必须至少包含{ config, pkgs, ... }: { home.username jane; home.homeDirectory /home/jane; home.stateVersion 20.09; }如果 Home Manager 以 NixOS 或 nix-darwin 子模块方式安装这两个选项会自动继承osConfig.users.users.name.home与同名用户名无需手工填写。XDG 基础目录默认值的确定性化与上述变更配套20.09 起xdg.cacheHome、xdg.configHome、xdg.dataHome以及xdg.binHome、xdg.stateHome不再读取XDG_CACHE_HOME、XDG_CONFIG_HOME、XDG_DATA_HOME等环境变量而是无条件默认到选项20.09 起的新默认值xdg.cacheHome${config.home.homeDirectory}/.cachexdg.configHome${config.home.homeDirectory}/.configxdg.dataHome${config.home.homeDirectory}/.local/sharexdg.binHome${config.home.homeDirectory}/.local/binxdg.stateHome${config.home.homeDirectory}/.local/state这一现代确定性分支在 modules/misc/xdg/default.nix 中实现# Modern deterministic setup. (mkIf (!cfg.enable lib.versionAtLeast config.home.stateVersion 20.09) { xdg.cacheHome mkOptionDefault defaultCacheHome; xdg.configHome mkOptionDefault defaultConfigHome; xdg.dataHome mkOptionDefault defaultDataHome; xdg.binHome mkOptionDefault defaultBinHome; xdg.stateHome mkOptionDefault defaultStateHome; })而 20.09 之前是传统非确定性分支会优先取环境变量、环境变量为空时才回退到默认值default.nix 中的getEnvFallback逻辑。因此如果你从未自定义过 XDG 基础目录升级无感默认路径保持不变如果你依赖XDG_CONFIG_HOME等环境变量指向非默认路径切到 20.09 后必须显式设置对应选项否则文件会被链接到默认路径下。对应行为有测试覆盖见 tests/modules/misc/xdg/default-locations.nix该测试在xdg.enable false、home.stateVersion 20.09的前提下断言xdg.configFile等文件被精确链接到.config、.local/share、.cache、.local/state四个默认位置证明 20.09 之后的求值结果与环境变量无关、完全确定。需要特别说明的是本仓库当前版本的 modules/misc/xdg/default.nix 中当xdg.enable true时XDG_CACHE_HOME等会话变量会在home.sessionVariables与systemd.user.sessionVariables中统一导出即便关闭xdg.enable20.09 分支也会让各*Home选项指向上述确定性默认值两条路径都不会再读外部环境变量。升级工具链的自动适配发布说明指出通过如下命令生成初始配置时若有必要会自动补上这些选项$ nix-shell home-manager -A install也就是说新用户通过安装脚本引导生成home.nix时20.09 及以后版本的模板会把home.username、home.homeDirectory、home.stateVersion以及必要的 XDG 路径选项一并写入避免改完状态版本后配置突然失效的坑。存量用户升级时建议对照上述表格逐一检查自己是否显式设置了 XDG 相关选项。Git sendemail 的 smtpEncryption 语义修正20.09 起accounts.email账号生成 Gitsendemail配置时smtpEncryption的取值逻辑被收紧仅当smtp.tls.enable true且smtp.tls.useStartTls true时才生成tls仅当smtp.tls.enable true而useStartTls未开启或为false时生成ssl两者皆不满足时为空字符串。对应实现位于 modules/programs/git.nixsmtpEncryption if smtp.tls.enable then (if smtp.tls.useStartTls || lib.versionOlder config.home.stateVersion 20.09 then tls else ssl) else ;注意其中的兼容分支lib.versionOlder config.home.stateVersion 20.09表示旧版本下只要开启 TLS 就一律用tls只有状态版本 ≥ 20.09 时才根据是否启用 STARTTLS 区分tls与ssl。这是典型的按状态版本拆分新旧语义的实现模式也说明同一份配置在不同stateVersion下可能生成不同的 Git 配置内容。相关行为由测试 tests/modules/programs/git/git-with-email.nixhome.stateVersion 20.09及配套的git-with-email-expected.conf期望文件验证。nixpkgs 模块不再引用nixpkgs20.09 之前构建pkgs模块参数时会隐式引用nixpkgs通道20.09 起pkgs改为从初始化 Home Manager 模块时所用的同一份 Nixpkgs构建。这对使用 Nix Flake 的场景尤其重要——此前 Flake 用户可能在无意中混合了两份不同的 Nixpkgs造成版本错配。源码依据见 modules/misc/nixpkgs.nix_pkgs import pkgsPath (lib.filterAttrs (_n: v: v ! null) config.nixpkgs);pkgsPath从_module.args注入同文件 L141 附近的_module.args { ... }其值在状态版本 ≥ 20.09 时默认指向初始化 Home Manager 所用的 Nixpkgs而非nixpkgs通道。如果你确实希望继续使用nixpkgs通道发布说明给出了显式声明方式_module.args.pkgsPath nixpkgs;将其加入 Home Manager 配置即可恢复旧行为。需要提示的是Home Manager 与 Nixpkgs 版本不匹配可能引发告警home-environment.nix 中的 release 检查因此保持两份 Nixpkgs 版本一致通常是更稳妥的选择。sway 与 i3 的 bars 选项改为可空nullable20.09 对wayland.windowManager.sway.config.bars与xsession.windowManager.i3.config.bars做了结构性调整大部分子选项变为null可空默认值统一为null同时为整个bars选项手工设置了一套旧默认值。这一设计的实现集中在共享选项模块 modules/services/window-managers/i3-sway/lib/options.nixmkNullableOption { type, default, ... }args: mkOption ( args // { type types.nullOr type; default if versionAtLeast2009 then null else default; defaultText literalExpression null for state version ≥ 20.09, as example otherwise ; } );而bars本身的默认值在 options.nix 中按状态版本区分bars mkOption { type types.listOf barModule; default if lib.versionAtLeast stateVersion 20.09 then [ { mode dock; hiddenState hide; position bottom; workspaceButtons true; workspaceNumbers true; statusCommand ${pkgs.i3status}/bin/i3status; fonts { names [ monospace ]; size 8.0; }; trayOutput primary; colors { /* 与旧版完全一致的配色默认值 */ }; } ] else [ { } ]; ... };整体效果是不设置bars时行为完全不变但只要显式写了bars未指定的子选项不再被旧默认值填满而是保持null生成配置时该行直接省略。发布说明给出的例子bars [ { command waybar; } ];20.09 之前会生成一段被旧默认值字体、模式、位置、i3status状态命令、workspace 按钮、tray、全套配色等填满的bar { ... }配置块20.09 之后只生成bar { swaybar_command waybar }command选项与生成逻辑的对应关系见 sway.nixcommand默认值为${pkg}/bin/${moduleName}bar生成时通过barStr渲染为swaybar_command/status_command等行。这意味着20.09 之后bars更像是增量声明你只写关心的字段其余交给 i3/sway 自身默认值若你此前依赖写一个command就自动附带全套 i3status 默认配置的旧行为升级后需要自行补齐statusCommand、colors等字段或直接不设置bars保持默认。升级到 20.09 的迁移检查清单综合发布说明与源码从旧状态版本切到home.stateVersion 20.09时建议依次核对必填项home.username与home.homeDirectory已在配置中显式给出XDG 路径若曾依赖XDG_CACHE_HOME/XDG_CONFIG_HOME/XDG_DATA_HOME等环境变量指向自定义路径需显式设置xdg.cacheHome/xdg.configHome/xdg.dataHome及xdg.binHome/xdg.stateHomeGit 邮件账号确认accounts.email.accounts.name.smtp.tls.enable与useStartTls的组合是否符合预期的tls/ssl取值Nixpkgs 来源确认pkgs是否应继续使用nixpkgs通道必要时添加_module.args.pkgsPath nixpkgs;sway/i3 状态栏检查bars是否显式设置、未指定字段是否会因null而被省略必要时补齐statusCommand、colors等。小结20.09 是 Home Manager 在可复现性方向上的一次集中收敛取消home.homeDirectory/home.username的环境变量默认值、将 XDG 基础目录改为确定性默认、让pkgs与初始化所用的 Nixpkgs 保持一致本质上都是在消除求值结果对外部环境与通道状态的隐式依赖。bars选项的 nullable 化则体现了另一条原则——选项默认值应当尽量由上游工具负责Home Manager 只做显式声明。理解这些变更背后的状态版本分支机制lib.versionOlder/versionAtLeast与20.09的组合也就掌握了阅读后续所有发布说明中 State Version Changes 的通用方法。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考