将 PyQt5 桌面应用（如我们的悬浮球）打包为 **Windows 独立 `.exe` 文件**，并满足以下要求： ✅ 无控制台窗口（`--noconsole`） ✅ 带自定义图标（`.ico` 文件嵌入） ✅ 单文件模式（`--onefile`），所有依赖打包进一个 `.exe` ✅ 兼容 Windows 10/11，无需用户安装 Python 或 PyQt5 ✅ 可静默运行、开机自启（后续可扩展） 我们推荐使用 **`PyInstaller`** —— 当前最成熟、对 PyQt5 支持最好的打包工具。 --- ### ✅ 完整步骤详解（含避坑指南） #### 🔹 步骤 1：准备图标文件（`.ico`） - 图标必须是 **Windows 标准 `.ico` 格式**（非 `.png` / `.jpg`！） - 推荐尺寸：`256×256`（高分屏兼容）、`48×48`、`32×32`、`16×16` 多尺寸合一（可用 [https://convertio.co/zh/png-ico/](https://convertio.co/zh/png-ico/) 或 [https://icoconvert.com](https://icoconvert.com) 在线生成） - 将图标保存为：`icon.ico`（与 `countdown_floating_ball.py` 同目录） > ⚠️ 常见错误：用 PNG 直接改后缀 → ❌ 不生效！必须真 `.ico` --- #### 🔹 步骤 2：安装 PyInstaller（建议使用虚拟环境） ```bash # 推荐先创建干净虚拟环境（避免依赖冲突） python -m venv venv_floating venv_floating\Scripts\activate # 升级 pip 并安装依赖 pip install --upgrade pip pip install PyQt5 # 安装 PyInstaller（>=6.0，支持 Python 3.9+ 和 PyQt5 5.15+） pip install pyinstaller ``` --- #### 🔹 步骤 3：执行打包命令（关键！带全部参数） 在项目目录下（即 `countdown_floating_ball.py` 所在文件夹），**以管理员身份打开 CMD/PowerShell**，运行： ```bash pyinstaller ^ --onefile ^ --windowed ^ --name "下班倒计时悬浮球" ^ --icon="icon.ico" ^ --add-data "venv_floating\Lib\site-packages\PyQt5\qt-plugins\platforms;PyQt5\qt-plugins\platforms" ^ --hidden-import=PyQt5.sip ^ --exclude-module=tkinter ^ --exclude-module=matplotlib ^ countdown_floating_ball.py ``` 📌 **Windows PowerShell 用户注意**：`^` 是续行符；若用 PowerShell，请改用反引号 `` ` ``，或**直接写成单行**（更稳妥）： ```powershell pyinstaller --onefile --windowed --name "下班倒计时悬浮球" --icon="icon.ico" --add-data "venv_floating\Lib\site-packages\PyQt5\qt-plugins\platforms;PyQt5\qt-plugins\platforms" --hidden-import=PyQt5.sip --exclude-module=tkinter --exclude-module=matplotlib countdown_floating_ball.py ``` ✅ 参数说明： | 参数 | 作用 | 必填？ | |------|------|--------| | `--onefile` | 打包为**单个 `.exe`**（所有依赖压缩进一个文件） | ✅ | | `--windowed`（等价于 `--noconsole`） | **隐藏黑框控制台**（关键！否则会弹 CMD 窗口） | ✅ | | `--name "xxx"` | 设置生成的 `.exe` 文件名（默认为脚本名） | ✅（推荐） | | `--icon="icon.ico"` | 指定程序图标（显示在任务栏、快捷方式、资源管理器中） | ✅（需存在） | | `--add-data "源路径;目标路径"` | **强制包含 PyQt5 的 `platforms` 插件**（否则运行报错：`Could not find the Qt platform plugin "windows"`）⚠️ | ✅（PyQt5 必加！） | | `--hidden-import=PyQt5.sip` | 显式导入 `sip`（PyQt5 内部模块，PyInstaller 可能漏扫） | ✅（防启动失败） | | `--exclude-module=xxx` | 排除无用模块（减小体积、加速启动） | ❌ 可选 | > 💡 提示：`--add-data` 路径中的 `venv_floating\Lib\...` 需根据你实际虚拟环境路径调整！ > ✅ 查找真实路径方法（在激活的 venv 中运行）： > ```python > import PyQt5 > print(PyQt5.__file__) > # 输出类似：...\venv_floating\Lib\site-packages\PyQt5\__init__.py > # 则 plugins 路径为：...\venv_floating\Lib\site-packages\PyQt5\qt-plugins\ > ``` --- #### 🔹 步骤 4：获取最终 `.exe` 文件 打包成功后，你会看到： ``` dist\ └── 下班倒计时悬浮球.exe ← ✅ 这就是你要的独立可执行文件！ build\ ← 中间产物，可删 countdown_floating_ball.spec ← 配置文件（可存档用于复现） ``` ✅ 双击 `下班倒计时悬浮球.exe` 即可运行 —— 无黑窗、有图标、可拖拽、功能完整！ --- ### 🛠️ 常见问题 & 解决方案（亲测有效） | 问题现象 | 原因 | 解决方案 | |----------|------|-----------| | ❌ 运行闪退，无任何提示 | 缺少 `platforms` 插件 | 确保 `--add-data` 路径正确，并验证 `dist\PyQt5\qt-plugins\platforms\qwindows.dll` 是否存在 | | ❌ 任务栏图标是白色方块 / 无图标 | `.ico` 路径错误 或 图标格式非法 | 用 [IcoFX](https://icofx.ro) 或在线工具重做 `.ico`；检查路径是否含空格/中文（建议全英文路径） | | ❌ 提示 `Failed to execute script xxx` | `PyQt5.sip` 未导入 | 加 `--hidden-import=PyQt5.sip`（PyQt5 5.15+ 必须） | | ❌ `.exe` 体积过大（>50MB） | 默认打包了所有 PyQt5 子模块 | 加 `--exclude-module` 排除 `QtWebEngine`, `QtSql`, `QtBluetooth` 等不用模块（本项目只需 `QtCore`, `QtGui`, `QtWidgets`） | | ❌ 悬浮球无法置顶 / 失去透明效果 | Windows 10/11 启用了“透明效果”开关关闭 | 设置 → 个性化 → 颜色 → 开启「透明效果」✅（非程序问题，是系统级渲染依赖） | --- ### ✅ Bonus：一键打包批处理脚本（`.bat`，推荐收藏） 新建文件 `build.bat`，内容如下（自动探测 venv 路径 + 安全打包）： ```bat @echo off setlocal enabledelayedexpansion :: ====== 配置区（按需修改）====== set APP_NAME=下班倒计时悬浮球 set MAIN_PY=countdown_floating_ball.py set ICON_FILE=icon.ico :: ============================== echo 🔍 正在查找 PyQt5 qt-plugins 路径... for /f "delims=" %%i in ('python -c "import PyQt5; print(PyQt5.__file__.replace('__init__.py','qt-plugins'))" 2^>nul') do set QT_PLUGINS=%%i if not defined QT_PLUGINS ( echo ❌ 错误：未找到 PyQt5 或未激活虚拟环境！请先运行 'venv_floating\Scripts\activate.bat' pause exit /b 1 ) echo ✅ 检测到 Qt 插件路径：%QT_PLUGINS% echo 🚀 开始打包... pyinstaller ^ --onefile ^ --windowed ^ --name "%APP_NAME%" ^ --icon="%ICON_FILE%" ^ --add-data "%QT_PLUGINS%\platforms;PyQt5\qt-plugins\platforms" ^ --hidden-import=PyQt5.sip ^ --exclude-module=tkinter ^ --exclude-module=matplotlib ^ %MAIN_PY% if %errorlevel% == 0 ( echo ✅ 打包成功！EXE 位于：dist\%APP_NAME%.exe explorer "dist" ) else ( echo ❌ 打包失败，请检查上方错误信息。 ) pause ``` > ✅ 将此 `.bat` 放在同目录，双击即可全自动打包（无需记命令）！ --- ### 📦 最终成果验证清单（打包后必检） | 项目 | 检查方式 | ✅ 成功标志 | |------|-----------|-------------| | 图标显示 | 右键 `.exe` → 属性 → “详细信息”页签 | 显示自定义图标 & 程序名 | | 无黑窗 | 双击运行 | **不弹 CMD 窗口**，直接显示悬浮球 | | 置顶透明 | 运行后切换到浏览器/微信 | 悬浮球始终在最前，背景半透明可见 | | 半点提醒 | 手动修改系统时间为 `xx:00` 或 `xx:30` | 触发抖动+变色+语录更新 | | 关闭测试 | 点右上角 × 或任务管理器结束进程 | 进程彻底退出，无残留 | ---