Cherry Studio macOS 透明窗口默认开启：变更说明、渲染原理与设置回退指南-开发者社区

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 机器上偏好值也是'transparent'，isMac为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.tsx）：

const 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"包含两条对发版有直接影响的要点，现结合仓库实现展开：

默认值写入所有平台，渲染仅限 macOS：'ui.window_style': 'transparent'是全局默认偏好（preferenceSchemas.ts），会在所有平台生效；但真正消费它的useMacTransparentWindow（useMacTransparentWindow.ts）与设置界面开关的渲染（AppearanceSettings.tsx）都被isMac门控。发版验证时应分别在 macOS 与 Windows/Linux 各检查一次，确认非 macOS 平台界面与背景行为无回归。
升级路径无感：由于默认值不覆盖已保存偏好，升级用户不会被强制改变外观；只需在 macOS 新装机场景验证首次启动即为透明窗口。