PyInstaller可将Python脚本打包为独立exe，实现双击运行、无需Python环境、隐藏黑框；需正确配置环境、使用-F和-w参数、处理资源路径及隐式依赖。
想让同事或客户双击就能运行你的Python脚本，不用装Python、不用配环境、不弹黑框——PyInstaller就是干这个的。它把你的.py文件、解释器、所有依赖库和资源一股脑打包进一个独立exe，目标机器连Python都不用装。
确认环境并安装PyInstaller
先打开PowerShell或CMD，检查Python是否就绪：【必须确保where python只返回一条路径，且不带WindowsApps】。如果出现多条，尤其是含“Microsoft\WindowsApps”的，说明装了微软商店版Python，它和pip不兼容，会直接导致打包失败。
执行以下三行命令：
python --version → 确认是3.6以上（推荐3.8–3.12）
where python → 只允许输出一行，且路径不含WindowsApps
python -m pip --version → 验证pip指向同一解释器
立即学习“Python免费学习笔记（深入）”；
满足条件后，用虚拟环境隔离依赖：python -m venv myenv → myenv\Scripts\activate → pip install pyinstaller
打包最简脚本（单文件+无黑框）
假设你有一个test.py，内容只是print("Hello")。把它放在D:\tools目录下。
在该目录下打开PowerShell，执行：
pyinstaller -F -w test.py
-F 表示打成单个exe文件，-w 表示不弹命令行窗口（对GUI程序必需）。这一步生成的exe默认叫test.exe，放在dist子目录里。
注意：如果你的脚本是.pyw后缀，-w参数可省略，但PyInstaller仍要求输入.py文件名，不能写test.pyw。
用于设计、审查、生成或重构使用Effector、effector-react、Farfetched、AtomicRouter、@effector/next等库的React应用。
处理图标、名称与资源文件
方法一：加图标和自定义名称
准备一个icon.ico文件（尺寸建议256×256，32位色），放在test.py同级目录。执行：
pyinstaller -F -w -i icon.ico -n MyTool test.py
方法二：打包带配置文件或图片的脚本
比如你的脚本读取data/config.json，必须显式告诉PyInstaller带上它：
pyinstaller -F -w --add-data "data;data" test.py
注意：Windows下--add-data分隔符是英文分号；Linux/macOS用冒号。路径必须是源码中相对路径的原始结构，不能写成绝对路径。
方法三：用spec文件精细控制（适合复杂项目）
先运行pyinstaller -F test.py生成test.spec，再用文本编辑器打开它，在a = Analysis(…)块里修改datas列表：
datas=[('data/config.json', 'data')],
改完保存，再执行pyinstaller test.spec即可生效。spec文件一旦存在，后续打包都优先读它，不再解析命令行参数。
解决打包后闪退或报错的关键步骤
第一步：先不加-F，用默认的--onedir模式打包一次
pyinstaller -w test.py → 运行dist\test\test.exe，观察是否正常。如果能跑通，说明代码逻辑和基础依赖没问题；如果报ModuleNotFoundError，说明有隐式导入没被自动识别。
第二步：补全缺失模块
常见于使用openpyxl、pandas、tkinter等库时。在命令中追加--hidden-import参数：
pyinstaller -F -w --hidden-import=openpyxl --hidden-import=pandas test.py
第三步：修复运行时资源路径
你的脚本若用os.path.dirname(__file__)获取当前路径，在exe里会失效。必须改用PyInstaller提供的sys._MEIPASS机制：
import sys, os
def resource_path(relative):
base = getattr(sys, '_MEIPASS', os.path.dirname(os.path.abspath(__file__)))
return os.path.join(base, relative)
然后把open("config.json")改成open(resource_path("config.json"))
第四步：验证exe是否真能脱离环境运行
把整个dist文件夹复制到一台**没装Python**的Windows电脑上，双击运行。如果闪退，按住Shift+右键→“在此处打开PowerShell窗口”→运行.\MyTool.exe，黑框会停留并显示具体错误。
