Cherry Studio macOS 透明窗口默认开启变更说明、渲染原理与设置回退指南【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio导读本文基于 Cherry Studio 仓库中的 breaking-changes 记录 2026-07-24-transparent-window-default.md系统讲解 macOS 平台透明窗口默认启用这一行为变更包括新安装用户与老用户默认值的差异、透明窗口背后的原生 vibrancy 渲染路径、Windows/Linux 平台的对照行为以及用户如何通过设置 → 显示与语言中的开关回退到不透明窗口。读完本文你将理解ui.window_style偏好项的前端驱动链路并能在实际使用中准确判断透明窗口何时生效、为何生效、如何关闭。本次变更的核心内容2026-07-24 的变更对应 PR #17350类别changed严重级别notice可概括为三点新安装用户默认透明新安装 Cherry Studio或本地未保存过窗口样式偏好的用户启动后默认使用透明窗口外观macOS 平台。已保存偏好的用户不受影响已经保存过窗口样式选择如选择过不透明窗口的用户升级后其既有选择保持不变不会被强制覆盖。用户无需任何操作该默认值面向所有平台写入存储但透明窗口这一设置项及透明渲染路径本身仍只对 macOS 生效。为什么默认值在 macOS 上如此重要macOS 使用原生 vibrancy 毛玻璃效果从源码看主窗口的基础配置同时声明了transparent: false与vibrancy: sidebar、visualEffectState: active见 windowRegistry.ts其中vibrancy是 Electron 在 macOS 上调用系统级毛玻璃材质的窗口能力。这意味着macOS应用外壳app shell会沿用首个可见窗口上已有的原生 vibrancy 外观让窗口内容与桌面背景自然融合形成半透明毛玻璃效果Windows行为保持不变继续使用 Mica 或纯色背景详见下文Windows 与 Linux 的对照行为Linux保持原有的窗口框架与背景行为。该默认配置由 WindowManager 的窗口类型注册表统一管理主窗口通过 MainWindowService.ts 打开时再注入动态选项如主题驱动的背景色、Linux 框架、缩放因子等但 vibrancy/透明相关基础配置以注册表静态默认值为准。已保存偏好不变的落地方式该变更的落地方式是修改ui.window_style偏好项的默认值而不是强制改写已保存的用户数据。仓库中偏好类型定义为export type WindowStyle transparent | opaque见 preferenceTypes.ts偏好默认值表中ui.window_style: transparent见 preferenceSchemas.ts对应测试断言默认值即为transparent见 preferenceSchemas.test.ts。偏好系统的运行机制是默认值只对没有保存过该键的用户生效。一旦用户通过设置界面切换过窗口样式保存值就会覆盖默认值——这正是老用户的既有选择不变的原理。同时这也解释了变更说明中新默认值存储在每个平台但设置项与透明渲染路径仍限定 macOS默认值写入是跨平台统一的而消费该值的行为是平台分支的。前端如何响应透明窗口驱动入口useMacTransparentWindow渲染进程通过一个专用 Hook 判断当前是否处于macOS 透明窗口状态// src/renderer/hooks/useMacTransparentWindow.ts import { usePreference } from data/hooks/usePreference import { isMac } from renderer/utils/platform function useMacTransparentWindow() { const [windowStyle] usePreference(ui.window_style) return isMac windowStyle transparent }该 Hook 同时满足两个条件才返回true当前运行平台是 macOS且偏好值恰好为transparent。这正是设置项与透明渲染路径限定 macOS的前端体现——即使 Windows 机器上偏好值也是transparentisMac为false时该 Hook 依然返回false。布局层的透明适配透明状态被 AppShell 等顶层布局组件消费用于切换背景类名AppShell.tsx根容器在透明模式下使用bg-transparent否则使用bg-sidebar让侧边栏区域透出 vibrancy 背景AppShellTabBar.tsx、Sidebar.tsx 同样基于该 Hook 做背景适配useWindowRuntime.ts 中定义了MAC_TRANSPARENT_NAV_BACKGROUND color-mix(in srgb, var(--background) 55%, transparent)用于将导航区域与 vibrancy 背景做半透明混合设置页同样感知透明状态透明模式下设置分组背景切换为transparent见 SettingsPage.tsx。用户如何回退设置界面操作开关位置在 macOS 上进入设置 → 显示与语言Settings Display Language的外观设置区即可找到透明窗口Transparent Window开关。它仅在isMac为真时渲染见 AppearanceSettings.tsx这也是该设置项在非 macOS 平台不显示的原因。开关的取值逻辑开关绑定的是ui.window_style偏好切换逻辑如下见 AppearanceSettings.tsxconst handleWindowStyleChange useCallback( (checked: boolean) { void setWindowStyle(checked ? transparent : opaque) }, [setWindowStyle] )即开关打开 → 偏好设为transparent开关关闭 → 偏好设为opaque。只要用户执行过一次该操作偏好值就会被持久化保存此后即使升级版本默认值变更也不会再影响该用户——这正是文档所述已保存窗口样式选择保持不变的行为闭环。Windows 与 Linux 的对照行为Windows继续使用 Mica 或纯色背景文档明确Windows 继续使用其既有的 Mica 或纯色背景行为。从源码看Windows 的材质由 windowUtil.ts 中的getWindowsBackgroundMaterial()决定仅当系统为 Windows 且构建号 ≥ 22621即 Windows 11 22H2时返回mica启用 Mica 半透明材质否则返回undefined主窗口退化为纯色背景深色主题#181818浅色主题#FFFFFF见 MainWindowService.ts。也就是说Windows 是否透明由系统版本与 Mica 能力决定与ui.window_style偏好无关。Linux保持既有框架行为Linux 下窗口框架遵循app.use_system_title_bar偏好图标与背景色由 MainWindowService 在打开窗口时注入见 MainWindowService.ts。透明窗口设置对其没有影响。给发布经理Release Manager的核对清单文档末尾的Notes for release manager包含两条对发版有直接影响的要点现结合仓库实现展开默认值写入所有平台渲染仅限 macOSui.window_style: transparent是全局默认偏好preferenceSchemas.ts会在所有平台生效但真正消费它的useMacTransparentWindowuseMacTransparentWindow.ts与设置界面开关的渲染AppearanceSettings.tsx都被isMac门控。发版验证时应分别在 macOS 与 Windows/Linux 各检查一次确认非 macOS 平台界面与背景行为无回归。升级路径无感由于默认值不覆盖已保存偏好升级用户不会被强制改变外观只需在 macOS 新装机场景验证首次启动即为透明窗口。变更验证与测试依据仓库中已为该行为提供测试佐证preferenceSchemas.test.ts显式断言ui.window_style默认值为transparent锁定本次变更的默认值事实AppShell.test.tsx、SettingsPage.test.tsx 等组件测试覆盖了透明模式下的类名与设置行为。如需在本地验证可运行渲染进程相关测试例如pnpm vitest run src/renderer/pages/settings/__tests__/SettingsPage.test.tsx具体命令以仓库 package.json 中的脚本为准。小结本次变更只动默认值不碰用户保存值新装或未保存过偏好的 macOS 用户默认进入透明窗口老用户保持不变透明窗口是 macOS 原生 vibrancy 能力由窗口注册表的vibrancy配置与渲染层的半透明背景类协同实现一键回退macOS 用户可在设置 → 显示与语言中关闭 Transparent Window偏好将被持久化为opaque跨平台对照Windows 的 Mica/纯色行为由系统版本决定Linux 遵循系统标题栏偏好二者均不受该默认值影响。若你是 Cherry Studio 的 macOS 新用户无需任何操作即可享受与系统融为一体的毛玻璃窗口若你更喜欢清晰不透明的窗口进入设置关闭一个开关即可永久生效。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
