PySide6安装失败或导入报错需确保Python与PySide6版本及架构匹配，优先用pip install PySide6；界面卡死须将耗时操作移至QThread或QThreadPool；打包后资源路径应基于sys._MEIPASS动态构建；高DPI适配需手动设置缩放因子与字体策略。
PySide6安装失败或导入报错怎么办
PySide6不是Python自带库，必须显式安装，且版本与Python解释器需严格匹配。常见错误如 ModuleNotFoundError: No module named 'PySide6' 或 ImportError: DLL load failed，多因环境混乱或架构不一致导致。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
python -m pip install --upgrade pip升级pip后再装，避免旧版pip解析wheel失败 - 优先使用
pip install PySide6（官方预编译包），不要用pip install pyside6-wheel等非官方变体 - 若用conda，统一用
conda install -c conda-forge pyside6，禁止混用pip和conda安装同一库 - Windows上遇到DLL错误，检查Python是x64还是ARM64——PySide6 6.7+已弃用32位支持，32位Python无法加载
窗口主循环卡死、按钮点击无响应的典型原因
PySide6是事件驱动框架，QApplication.exec() 启动后会接管主线程并阻塞后续代码执行。很多自动化脚本习惯把耗时操作（如文件处理、网络请求）直接写在按钮回调里，结果界面冻结、鼠标变成转圈、甚至被系统标记为“未响应”。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 所有可能超过100ms的操作，必须移出主线程：用
QThread+ 自定义信号，或更推荐的QThreadPool+QRunnable - 不要在槽函数里调用
time.sleep()、subprocess.run(..., capture_output=True)等同步阻塞调用 - 若需实时显示命令输出，用
QProcess替代subprocess，它原生支持readyReadStandardOutput信号 - 调试时加一句
print(f"Thread: {QThread.currentThread()}")，确认耗时逻辑确实在子线程中运行
打包成exe后图标丢失、中文乱码、找不到资源文件
PySide6应用打包后路径行为与开发期完全不同：__file__ 指向临时解压目录，os.getcwd() 可能是用户桌面，硬编码的相对路径必然失效。图标不显示、字体发虚、JSON配置读不到，本质都是资源定位失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
sys._MEIPASS判断是否在PyInstaller打包环境中，再拼接资源路径：os.path.join(sys._MEIPASS, "icons", "run.svg") - 图标必须用绝对路径传给
QIcon，且格式优先选.svg或.png（.ico在高DPI下易模糊） - 中文显示问题大概率是字体缺失：显式设置
QFont("Microsoft YaHei", 10)或打包时加入--add-data "fonts;fonts" - 用
PyInstaller --onefile --windowed --icon=app.ico main.py打包，--windowed防止控制台闪退干扰GUI
跨平台字体渲染差异与高DPI适配坑点
PySide6默认启用高DPI缩放，但Windows/macOS/Linux对 Qt::AA_EnableHighDpiScaling 的实现不一致：macOS下文字边缘常发虚，Linux（尤其是Wayland）下按钮尺寸忽大忽小，Windows上4K屏可能放大两倍却没缩放UI元素。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 启动前强制设置环境变量：
os.environ["QT_SCALE_FACTOR"] = "1.25"（按实际缩放比调整），比依赖自动检测更稳 - 禁用全局缩放后手动适配：调用
QGuiApplication.setHighDpiScaleFactorRoundingPolicy(Qt.HighDpiScaleFactorRoundingPolicy.PassThrough) - 字体大小别写死
12，改用qApp.font().pointSize() * 1.1动态计算 - Linux上若用Wayland，启动命令加
QT_QPA_PLATFORM=wayland或回退到xcb，避免部分控件不可点击
真正难的不是写出能跑的界面，而是让同一套代码在不同系统、不同缩放、不同DPI下都保持可用性——资源路径、线程模型、字体策略这三点，漏掉任一个都会在交付时突然暴露。
