# 【AI 工作流手记 #6】桌面浮窗的三个真坑：亚克力磨砂、刷新把进程搞消失、后台启动像闪退

## 起因：一个"抬头就能看见"的桌面小窗

我想要一个常驻桌面角落的小窗：显示"有几件事在等你、后台任务还在跑几个"，数据来自本机几份只读日志。要求四条——**常驻但不碍事**（不占任务栏、置顶可选）、**半透明磨砂**、**内容有变化才动**、**托盘能收起来**。

选了 PySide6。起因很朴素：手上的 Python 是精简构建，没有 tkinter；而 Qt 的无边框窗口、系统托盘、自绘背景都是现成的。先记两个装环境时的真实数字，方便你对成本有概念：

- PySide6-Essentials 6.12.0 装进隔离目录（`pip install --target`），落盘 **220MB**，一次约 2 分钟；
- `import PySide6.QtWidgets` 首次约 **0.8 秒**——常驻程序一次性成本可以接受，但别在循环里反复起进程。

写完第一版，1 小时内连踩三个坑。这三个坑的共同点是：**症状都像 UI 问题，根子全是工程问题**。

## 关键发现一：磨砂不是"设个透明度"

第一反应是 `setWindowOpacity(0.7)`——结果是整窗一起变淡，文字也跟着看不清。它调的是"窗口整体不透明度"，不是"背景模糊"。

第二反应是 `WA_TranslucentBackground`——背景是掏空了，但背后是**清晰的桌面**，文字直接浮在桌面上，糊不掉。

真正的"磨砂"是**系统合成器**的事，Qt 没有跨平台封装。Windows 10 上得走 `SetWindowCompositionAttribute`，把一个 `ACCENT_ENABLE_ACRYLICBLURBEHIND` 的策略结构体塞给系统。实测一台 Win10 开发机：调用本身只要 **0.148ms**，重复调用幂等（返回同样成功），是一次性成本。

但这条路有三个必须知道的细节，全在代码里：

```python
import ctypes


class ACCENT_POLICY(ctypes.Structure):
    _fields_ = [
        ("AccentState", ctypes.c_int),
        ("AccentFlags", ctypes.c_int),
        ("GradientColor", ctypes.c_uint),   # 注意是 AABBGGRR，不是常见的 RRGGBBAA
        ("AnimationId", ctypes.c_int),
    ]


class WINCOMPATTRDATA(ctypes.Structure):
    _fields_ = [
        ("Attribute", ctypes.c_int),        # WCA_ACCENT_POLICY = 19
        ("Data", ctypes.c_void_p),
        ("SizeOfData", ctypes.c_size_t),
    ]


ACCENT_ENABLE_ACRYLICBLURBEHIND = 4
WCA_ACCENT_POLICY = 19


def enable_acrylic(widget, gradient, state=ACCENT_ENABLE_ACRYLICBLURBEHIND):
    """给一个【已 show】的窗口开亚克力模糊。gradient 按 AABBGGRR 拼。"""
    hwnd = int(widget.winId())              # 必须 show() 之后再调，才有真句柄
    policy = ACCENT_POLICY(state, 2, gradient & 0xFFFFFFFF, 0)
    data = WINCOMPATTRDATA(
        WCA_ACCENT_POLICY,
        ctypes.cast(ctypes.byref(policy), ctypes.c_void_p),
        ctypes.sizeof(policy),
    )
    return bool(ctypes.windll.user32.SetWindowCompositionAttribute(
        ctypes.c_void_p(hwnd), ctypes.byref(data)))


# gradient = 0xB01A2233 → AA=B0(半透明), BB=33, GG=22, RR=1A
# enable_acrylic(panel, 0xB01A2233)
```

细节一：**必须在 `show()` 之后调**。实测 `show()` 到能拿到真句柄约 39ms，在窗口显示前调用拿到的句柄不是最终的那个。细节二：**结构体字段顺序和 `SizeOfData` 一个都不能错**——这个 API 出错是**静默的**，返回 0、不抛异常，窗口看起来一切正常，就是没有磨砂。64 位下先断言 `ctypes.sizeof(ACCENT_POLICY) == 16`、`sizeof(WINCOMPATTRDATA) == 24`，错了立刻知道。细节三：**颜色是 AABBGGRR**，按 RGBA 惯例拼色号，磨出来的会是另一种颜色。

还有一层容易忽略：磨砂开了之后，如果你又用样式表给面板铺一层**不透明底色**，效果就被盖死了。实测把底色的 alpha 压到 **140~170/255** 这个区间，既能让模糊透出来，又能保证文字对比度够。

## 关键发现二：验证磨砂，抓控件是抓不到的

开完磨砂想截图确认效果，第一反应是 `panel.grab()`。实测结果很有意思：抓下来的图中心像素是 **(0,0,0) 且 alpha=0**——完全透明。

原因是 `grab()` 只抓窗口**自己的绘制内容**，而磨砂发生在窗口**外面**（系统合成器把桌面模糊后垫在底下）。所以从窗口内部看，自己依旧是一片透明。

验证磨砂必须抓**屏幕**。用 Pillow 的 `ImageGrab.grab` 按窗口几何抓一块：

```python
from PIL import ImageGrab, ImageStat

# 窗口 geometry() 给的是逻辑坐标，DPI 缩放的机器要乘 devicePixelRatio
dpr = 1.0                                   # 我的机器是 100% 缩放
g = panel.geometry()
bbox = (int(g.x() * dpr), int(g.y() * dpr),
        int((g.x() + g.width()) * dpr), int((g.y() + g.height()) * dpr))
im = ImageGrab.grab(bbox=bbox, all_screens=True)

st = ImageStat.Stat(im.convert("RGB"))
print(im.size, [round(v, 1) for v in st.mean], [round(v, 1) for v in st.stddev])
# 实测输出：(340, 150) [98.4, 88.3, 83.7] [13.8, 15.7, 17.4]
```

标准差 14~17 说明这块区域内**有明暗变化**——模糊的桌面透出来了，磨砂确实生效；如果磨砂没开，抓到的会是一片均匀的桌面原色或纯色。顺带一个坑：`bbox` 要乘 `devicePixelRatio`，否则在 125%/150% 缩放的机器上抓的位置整体偏移。

## 关键发现三：刷新不是"重画"，重画会出人命

浮窗内容每十几秒轮换一次。第一版图省事：定时器到点，把面板里的控件全拆了重建。实测（离屏模式、每轮 20 个控件、跑 50 轮）直接成本很低——重建一轮 **0.89ms**。但它有个延迟爆炸的毛病：**长跑之后进程会凭空消失**——没有 Python 异常栈，`faulthandler` 也没截到 Python 层的东西，只能判定为 Qt 原生层崩溃。`setParent(None)` 把控件摘下来之后生命周期悬空，重建一多就踩到原生层的雷。

正确姿势是三件套：

1. **数据签名**：把要展示的数据拼成一个元组，签名没变就直接 `return`；
2. **变化才重建**：真变了才动控件；
3. **`deleteLater()`**：旧控件交给事件循环回收，别用 `setParent(None)` 之后不管。

```python
from PySide6.QtCore import QTimer


class Refresher:
    """定时刷新器：签名没变就跳过，变了才重建。"""

    def __init__(self, build, interval_ms=1000):
        self._build = build              # build(items) 负责把数据画上去
        self._sig = None
        self._timer = QTimer()
        self._timer.timeout.connect(self.tick)
        self._timer.start(interval_ms)

    def tick(self, items=()):
        sig = tuple(items)               # 数据签名：可哈希即可
        if sig == self._sig:             # 绝大多数轮次走这条路
            return
        self._sig = sig
        self._build(items)               # 少数轮次才真正重建
```

三组实测数字放在一起看就明白为什么值得做：

| 操作（20 个控件规模） | 实测耗时 | 相对代价 |
|---|---|---|
| 全量重建一轮 | 0.89 ms | 1×（基准） |
| `deleteLater` + 重建一轮 | 1.05 ms | 1.2× |
| **签名比对、跳过重建** | **3.7 µs** | **约 1/240** |

如果面板有多个页面（工作 / 成长 / 提醒三块轮着显示），还有第四个数字：用 `QStackedWidget` 把三页**建一次、切 index**，实测切一次 **11.7µs**；对比每次切换重建同规模面板的 **1299.5µs**，差 **111 倍**。结论很干脆：**面板构造贵、切换便宜，那就永远别在切换和刷新时重新构造。**

最后补一道保险：常驻 GUI 程序上线前挂上 `faulthandler`（落盘）和 `sys.excepthook`。原生崩溃抓不到 Python 栈，但"进程消失的时间点 + 最后一条日志"足够把范围缩小到"哪次刷新之后"。

## 关键发现四：进程"闪退"，多半根本没崩

用 `pythonw` 启动（不弹控制台窗），从临时 shell 里用 `(pythonw app.py &)` 脱离启动——命令一结束，子进程跟着被回收，窗口一闪而过。看起来是闪退，**其实进程根本没崩，是被爹带走了**。

判别方法一行日志就够：程序启动第一行先写"启动成功"。闪退时看日志——

- 有"启动成功" → 起来过，后来被杀 → 查生命周期（谁拉起的、谁回收的）；
- 没有 → 根本没起来 → 查 Python 路径、依赖目录（`PYTHONPATH`）、工作目录。

解法：常驻进程交给**启动文件夹的 .bat** 或计划任务拉起，别从一次性 shell 里脱离。

## 踩坑表：八个真踩过的

| 坑 | 现象（实测） | 解法 |
|---|---|---|
| 拿 `setWindowOpacity` 当磨砂 | 整窗变淡，文字看不清 | 磨砂走系统合成器 API；透明度只给底色用 |
| `show()` 之前开磨砂 | 拿到的句柄不是最终窗口的 | 先 `show()`（实测约 39ms）再调 |
| 结构体字段顺序/`SizeOfData` 写错 | **返回 0、不抛异常**，看似正常实则没磨砂 | 64 位下断言 `sizeof` = 16 / 24 |
| 颜色按 RGBA 拼进 `GradientColor` | 磨出来颜色不对 | 它是 **AABBGGRR** |
| 底色不透明 | 磨砂"开了没效果" | 底色 alpha 压到 140~170/255 |
| 用 `panel.grab()` 验证磨砂 | 中心像素 alpha=0，抓不到效果 | 抓屏幕（`ImageGrab`），bbox 乘 DPR |
| 定时器里全量重建控件 | 长跑后进程凭空消失，无 Python 异常 | 签名比对 + 变化才重建 + `deleteLater` |
| `(pythonw &)` 脱离启动 | 窗口一闪而过，像闪退 | 启动日志 + 交给启动项/计划任务拉起 |

## 效果

- **刷新成本**：从 0.89ms/轮降到 3.7µs/轮（约 **240×**），多页面板从 1299.5µs/次降到 11.7µs/次（**111×**）。对一个 12 秒一轮的浮窗，这笔账本身不大，但"变化才重建"换来的是**不再崩**——这才是大头。
- **稳定性**：改成签名 + `deleteLater` 后连续长跑稳定，此前重建策略下进程消失的现象不再复现。
- **磨砂**：一次性 0.148ms，幂等可重开；自绘内容保持透明，模糊由系统合成，主线程零负担。
- **体积与启动**：220MB 隔离安装、首次 import 约 0.8s，常驻程序一次性成本，可接受。

## 你可以怎么用

1. **最小浮窗三件套**：`FramelessWindowHint | Tool | WindowStaysOnTopHint` + `WA_TranslucentBackground`，再加一个系统托盘图标——十几行就是一个能收进托盘的常驻小窗。
2. **磨砂 = `SetWindowCompositionAttribute`**：先 `show()` 再调；结构体尺寸先断言；颜色记 AABBGGRR；底色 alpha 留 140~170。
3. **刷新一律"签名 + 变化才重建 + `deleteLater`"**；多页面板用 `QStackedWidget` 建一次切 index，永远别在切换时重新构造。
4. **验证视觉效果抓屏幕，别抓控件**——凡是系统合成器参与的效果（磨砂、阴影），窗口自己 `grab()` 都看不见。
5. **常驻进程先打启动日志再谈"闪退"**：区分"没起来"和"起来后被杀"，两种病两种药。

---

> **关于作者**：10 年跨境电商老兵，拥抱 AI 时代。这里记录我踩过的坑和跑通的方法。

---

我想要一个常驻桌面角落的小窗：显示"有几件事在等你、后台任务还在跑几个"，数据来自本机几份只读日志。要求四条——常驻但不碍事（不占任务栏、置顶可选）、半透明磨砂、内容有变化才动、托盘能收起来。

【AI 工作流手记 #6】桌面浮窗的三个真坑：亚克力磨砂、刷新把进程搞消失、后台启动像闪退

用 PySide6 做常驻桌面浮窗。离屏实测：全量重建面板 0.89ms/轮，签名比对跳过只要 3.7µs；附 Windows 亚克力磨砂的 ctypes 写法与三个必踩的坑。

客户端

编程语言

操作系统

PySide6桌面浮窗开发避坑指南：亚克力磨砂需在show()后调用SetWindowCompositionAttribute，注意AABBGGRR颜色格式；刷新控件采用签名比对+deleteLater，性能提升240倍；验证效果需抓屏幕而非grab()；区分闪退与进程被回收。附完整代码与实测数据，助你快速实现稳定常驻浮窗。

代码解释

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

PySide6桌面浮窗开发避坑指南：亚克力磨砂需在show()后调用SetWindowCompositionAttribute，注意AABBGGRR颜色格式；刷新控件采用签名比对+deleteLater，性能提升240倍；验证效果需抓屏幕而非grab()；区分闪退与进程被回收。附完整代码与实测数据，助你快速实现稳定常驻...

【AI 工作流手记 #6】桌面浮窗的三个真坑：亚克力磨砂、刷新把进程搞消失、后台启动像闪退-腾讯云开发者社区-腾讯云

【AI 工作流手记 #6】桌面浮窗的三个真坑：亚克力磨砂、刷新把进程搞消失、后台启动像闪退

【AI 工作流手记 #6】桌面浮窗的三个真坑：亚克力磨砂、刷新把进程搞消失、后台启动像闪退

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐