PyQt5 开发“隐蔽坑”避雷指南
1. 样式表（QSS）的“父子传染”问题
场景：你想给一个容器（如 QFrame 或 QWidget）设置背景色。
代码：
my_frame.setStyleSheet("background-color: red;")
现象：不仅这个 Frame 变红了，放在里面的所有按钮、下拉框、标签全部都变红了，甚至变成了红色方块。
原因：Qt 的样式表具有级联继承性（Cascading）。如果没有指定选择器，样式会应用到该控件及其所有子控件上。
解决：必须指定类名或对象名（ID）。
/* 写法 1：指定类名（只影响该 Frame 本身，不影响子控件） */
.QFrame { background-color: red; }
/* 写法 2：指定对象名（更精准） */
#myObjectName { background-color: red; }
2. 局部变量引发的“窗口闪退”
场景：在一个函数里实例化并显示一个新的窗口。
代码：
def open_new_window(self):
win = MySubWindow() # 局部变量
win.show()
现象：窗口闪了一下就立刻消失了，没有任何报错。
原因：Python 的垃圾回收机制（GC）。win 是局部变量，函数执行结束时，引用计数归零，Python 销毁了对象。虽然 C++ 端的窗口显示了，但 Python 端的对象被杀死了，导致窗口关闭。
解决：保持引用。
def open_new_window(self):
# 保存为成员变量，增加引用计数
self.sub_window = MySubWindow()
self.sub_window.show()
3. Lambda 表达式在循环中的“闭包陷阱”
场景：循环创建 10 个按钮，希望点击第 i 个按钮打印 i。
代码：
for i in range(10):
btn = QPushButton(f"Button {i}")
# 错误写法
btn.clicked.connect(lambda: print(i))
现象：无论点击哪个按钮，打印的数字全是 9（最后一个值）。
原因：Python 的 lambda 是延迟绑定的，它查找的是变量 i 的内存地址，而不是循环时的值。循环结束时，i 变成了 9。
解决：使用默认参数锁定值。
# 正确写法：把当前的 i 赋值给 lambda 的局部变量 val
btn.clicked.connect(lambda checked, val=i: print(val))
(注意：clicked 信号默认发一个 boolean 参数，lambda 需要占位符或者忽略)
4. 线程（QThread）操作 UI 导致的“随机崩溃”
场景：在后台线程下载文件，下载完直接更新进度条或弹窗。
代码：
# 在线程 run 方法里
self.progressBar.setValue(100) # 致命错误
现象：程序有时正常，有时直接无报错闪退（Crash），有时界面卡死。
原因：GUI 框架通常不是线程安全的。只有主线程（Main Thread）才能操作 UI 控件。子线程直接修改 UI 内存会导致竞争条件。
解决：使用信号（Signal）。
- 子线程
emit信号 -> 主线程槽函数接收信号 -> 主线程更新 UI。
5. 图片/资源在打包（PyInstaller）后不显示
场景：代码里写 QIcon('icon.png')，IDE 里运行正常，打包成 exe 后图片不见了。
代码：
self.setWindowIcon(QIcon('my_icon.png'))
现象：图标丢失，界面光秃秃。
原因：打包后的临时解压路径（_MEIPASS）与开发时的当前工作目录（CWD）不一致。
解决：编写资源路径转换函数。
import os, sys
def resource_path(relative_path):
# PyInstaller 创建临时文件夹，路径存储在 _MEIPASS 中
if hasattr(sys, '_MEIPASS'):
base_path = sys._MEIPASS
else:
base_path = os.path.abspath(".")
return os.path.join(base_path, relative_path)
# 使用
self.setWindowIcon(QIcon(resource_path('my_icon.png')))
6. QTimer/QThread 被过早回收
场景：在方法里启动一个定时器。
代码：
def start_task(self):
timer = QTimer()
timer.timeout.connect(self.do_something)
timer.start(1000)
现象：定时器根本不运行，或者只运行一次。
原因：同第 2 点，timer 是局部变量，函数运行完就被 Python 回收了。
解决：self.timer = QTimer() 或者指定父对象 timer = QTimer(self)（Qt 的父子对象机制会接管内存管理）。
7. 布局（Layout）不生效
场景：创建了布局，添加了控件，但窗口还是乱的，控件堆在左上角。
代码：
layout = QVBoxLayout()
layout.addWidget(btn)
# 漏了关键一步
现象：控件没有按布局排列。
原因：布局没有应用到窗口上。
解决：
- 初始化时传入父窗口：
layout = QVBoxLayout(self) - 或者显式设置：
self.setLayout(layout) - 如果是在
QMainWindow中，由于其特殊的结构，必须应用到中心部件：widget = QWidget() widget.setLayout(layout) self.setCentralWidget(widget)
8. 高分屏（4K）下字体模糊或界面错位
现象：在 Windows 缩放 150% 或 200% 的屏幕上，PyQt 程序看起来模糊，或者窗口尺寸计算错误。
解决：在 QApplication 实例化之前添加以下代码：
from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QApplication
# 开启高 DPI 适配
QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
app = QApplication(sys.argv)
这些都是新手进阶到中级开发者时最容易撞到的墙。把这份列表和你的 QComboBox 笔记放在一起，能帮你节省大量的 Debug 时间！