Multipass 的 Windows Terminal 集成设置：client.apps.windows-terminal.profiles 详解

• 虚拟化
• 开发工具
• 云原生

client.apps.windows-terminal.profiles是 Multipass 在 Windows 平台上控制 Windows Terminal（终端应用）集成的设置键。它决定 Multipass 是否会在 Windows Terminal 中注册一个名为 "Multipass" 的配置文件（Profile），从而让你打开一个终端标签页即可直接进入 primary 实例的 shell。读完本文，你将掌握该设置键的可选值、默认行为、配置命令，以及它在仓库源码层面的完整实现原理。

设置键与作用范围

该设置的完整键名为：

client.apps.windows-terminal.profiles

从键名结构可以看出，它属于client（客户端）命名空间下的apps.windows-terminal（Windows Terminal 应用集成）分组。在源码中，该键被定义为常量winterm_key：

// include/multipass/constants.h constexpr auto winterm_key = "client.apps.windows-terminal.profiles";

同时，源码还定义了一个固定的 Profile GUID，用于在 Windows Terminal 配置文件中标识 Multipass 专属的 profile：

// include/multipass/constants.h constexpr auto winterm_profile_guid = "{aaaa9e6d-1e09-4be6-b76c-82b4ba1885fb}"; // identifies the primary Multipass profile in Windows Terminal

这意味着 Multipass 写入 Windows Terminal 配置的 profile 具有稳定、唯一的标识符，Multipass 可以据此查找、隐藏或删除它。

可选值与生效行为

该设置支持以下两个值：

值的校验逻辑

源码对取值做了严格校验（大小写不敏感，会先转小写）：

// src/platform/platform_win.cpp QString interpret_winterm_setting(const QString& val) { static const auto acceptable = QStringList{none, mp::petenv_default}; // "none" 与 "primary" auto ret = val.toLower(); if (!acceptable.contains(ret)) throw mp::InvalidSettingException{ mp::winterm_key, val, QStringLiteral("Unknown value. Try one of these: %1.").arg(acceptable.join(", "))}; return ret; }

如果传入primary、none之外的任何值，Multipass 会抛出InvalidSettingException，提示 "Unknown value. Try one of these: none, primary."。这一校验行为有对应的单元测试覆盖，见 tests/unit/windows/test_platform_win.cpp（其中验证了合法值原样返回、非法值抛异常等分支）。

默认值

默认值为primary，即只要检测到系统安装了 Windows Terminal，Multipass 就会尝试为其添加一个 primary 实例的 profile。

该默认值在平台层的客户端扩展设置中注册，并复用了 primary 实例的默认名常量：

// src/platform/platform_win.cpp auto mp::platform::Platform::extra_client_settings() const -> SettingSpec::Set { SettingSpec::Set ret; ret.insert( std::make_unique<CustomSettingSpec>(winterm_key, petenv_default, [](const QString& val) { return interpret_setting(winterm_key, val); })); return ret; }

这里的petenv_default即"primary"（见 include/multipass/constants.h）。需要留意的是，这是 Windows 平台特有的客户端设置——在 Linux、macOS 上该键不可用（interpret_setting会因键不匹配抛出 "Setting unavailable on Windows" 异常），相关限制可参考 docs/explanation/platform.md。

配置示例：查询与设置

使用multipass get查询当前值：

multipass get client.apps.windows-terminal.profiles

使用multipass set修改：

multipass set client.apps.windows-terminal.profiles=primary multipass set client.apps.windows-terminal.profiles=none

提示：get与set是 Multipass 的通用设置管理命令，完整用法见 get 与 set。

底层实现：Multipass 如何修改 Windows Terminal 配置

目标配置文件的位置

Multipass 不会直接调用 Windows Terminal 的 API，而是定位并修改其配置 JSON 文件：

$env:LocalAppData\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json

其中$env:LocalAppData通常为C:\Users\<USER>\AppData\Local。源码中通过locate_profiles_path()使用 Qt 的GenericConfigLocation标准路径定位该文件：

// src/platform/platform_win.cpp QString locate_profiles_path() { // The profiles file is expected in // $env:LocalAppData\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json return MP_STDPATHS.locate( mp::StandardPaths::GenericConfigLocation, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json"); }

生成的 profile 内容

当设置为primary且目标 profile 不存在时，Multipass 会向 Windows Terminal 的profiles列表追加一个名为 "Multipass" 的 profile：

// src/platform/platform_win.cpp Json::Value create_primary_profile() { Json::Value primary_profile{}; primary_profile["guid"] = mp::winterm_profile_guid; primary_profile["name"] = "Multipass"; primary_profile["commandline"] = "multipass shell"; primary_profile["background"] = "#350425"; primary_profile["cursorShape"] = "filledBox"; primary_profile["fontFace"] = "Ubuntu Mono"; primary_profile["historySize"] = 50000; primary_profile["icon"] = QDir{QCoreApplication::applicationDirPath()}.filePath("multipass_wt.ico").toStdString(); return primary_profile; }

各字段的含义与效果：

• guid：固定值{aaaa9e6d-1e09-4be6-b76c-82b4ba1885fb}，用于后续定位该 profile；
• name：显示在 Windows Terminal 新建标签页下拉菜单中的名称 "Multipass"；
• commandline：multipass shell，即打开该 profile 时执行的命令——进入 primary 实例的 shell（如果 primary 实例未启动，Multipass 会自动启动或拉起它）；
• background：背景色#350425（深紫色）；
• cursorShape：光标形状filledBox（实心方块）；
• fontFace：等宽字体Ubuntu Mono；
• historySize：滚动缓冲区 50000 行；
• icon：Multipass 随安装包提供的图标文件multipass_wt.ico。

此外，wt_patch_colors还会对cursorColor/foreground做兜底修补（#FDFDFD），解决白色显示成浅绿色的问题，除非用户已有自定义值（见src/platform/platform_win.cpp中的wt_patch_colors）。

添加、隐藏与移除的逻辑

update_profiles()的核心逻辑是：按 GUID 在现有 profiles 中查找 Multipass profile——

• 若已存在且被标记为hidden，或当前设置值为none，则将该 profile 的hidden字段设为true（none时隐藏，而不是删除条目）；
• 若不存在且当前设置不是none，则调用create_primary_profile()追加新 profile。

// src/platform/platform_win.cpp auto primary_profile_it = std::find_if(..., [](const auto& profile) { return profile["guid"] == mp::winterm_profile_guid; }); ... else if (winterm_setting != none) primary_profile_ptr = &profiles.append(create_primary_profile());

写入时 Multipass 采用"临时影子文件 + 原子替换"的方式（create_shadow_config_file+save_profiles），避免直接破坏 Windows Terminal 正在读取的配置文件。

同步触发的时机

每次客户端启动完成后，都会调用平台层的sync_winterm_profiles()来同步 Windows Terminal 的配置：

// src/client/common/client_common.cpp void mp::client::post_setup() { platform::sync_winterm_profiles(); }

synchronize_winterm_profiles()的完整流程为：

1. 定位settings.json；
2. 读取当前设置值（MP_SETTINGS.get(mp::winterm_key)）；
3. 读取并解析 Windows Terminal 配置 JSON；
4. 根据设置值更新 profiles；
5. 若内容有变化则写回文件；
6. 对 "未找到配置文件 / 解析失败 / 写入失败" 等不同严重程度的问题，分级记录日志（debug/info/warning/error），而不会直接崩溃（见 src/platform/platform_win.cpp）。

也就是说：只要你不手动修改该设置，Multipass 每次客户端运行都会尝试补齐缺失的 Multipass profile；若配置文件中缺少profiles节点等异常情况，则以日志形式记录，不影响 Multipass 主体功能。

使用效果

完成multipass set client.apps.windows-terminal.profiles=primary后，在 Windows Terminal 中点击新建标签页的下拉菜单，即可看到 "Multipass" profile，选择它即自动进入 primary 实例的 shell：

撤销集成

若想恢复原状，将设置改回none：

multipass set client.apps.windows-terminal.profiles=none

Multipass 随后会在下次同步时隐藏（而非删除）已存在的 Multipass profile。更完整的启用、使用与撤销步骤可参考 How to integrate with Windows Terminal。

相关参考

• 命令参考：get、set
• 操作指南：How to integrate with Windows Terminal
• 平台能力说明：docs/explanation/platform.md
• 源码：设置键定义 include/multipass/constants.h、Windows 平台实现 src/platform/platform_win.cpp、客户端启动同步入口 src/client/common/client_common.cpp
• 测试：设置值校验 tests/unit/windows/test_platform_win.cpp、全局设置键白名单 tests/unit/test_global_settings_handlers.cpp

• 虚拟化
• 开发工具
• 云原生