VSCode Python打包exe全攻略：从环境搭建到PyInstaller踩坑实战

每个学Python的人，迟早都会遇到同一个尴尬时刻：脚本在自家电脑上跑得风生水起，同事或朋友想看下效果，你只能把整个项目文件夹发过去，然后跟一句“帮我装个Python，得选3.11以上，依赖我写requirements.txt了”。对方打开一看，满屏红色报错，当场就没了兴趣。

VSCode + Python + exe，这套组合解决的就是这个痛点。用VSCode写Python代码，再把写好的脚本打包成exe，让目标用户双击就能运行，不用装解释器、不用配环境变量、不用被依赖问题折磨。这篇文章我会从零开始捋一遍完整流程，包括环境搭建、代码改造、工具选型的逻辑、打包命令的参数含义，以及我实际打包过程中踩过的各种坑。适合刚学Python不久、想把脚本分享给别人的新手，也适合已经在用PyInstaller但经常遇到奇怪问题的老手。

1. 环境搭建：VSCode装了Python插件，为什么运行还是报“No module named”？

1.1 第一个老板键：安装Python时必须勾选“Add Python to PATH”

很多新手下载Python安装包时，看到“Use admin privileges when installing py.exe”“Add python.exe to PATH”这两个选项，会觉得后面那个是系统高级用户才需要的，于是取消勾选直接装完。结果打开VSCode写第一行print("hello")，系统就懵了——'python' 不是内部或外部命令。

这个勾选干的事情很简单：把Python安装目录写进Windows的环境变量PATH。系统执行命令时，会按PATH里列出的目录依次找可执行文件，找不到才报错。不勾选，你只是在“已安装”的意义上有了Python，Shell里却找不到它。

如果你已经装完了、没勾选，不需要卸载重装。手动把路径加进去就行：找到Python安装目录和其中的Scripts目录，一般长这样：

code复制C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\
C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\Scripts\

然后“系统属性 -> 环境变量 -> Path -> 编辑 -> 新建”，把两个路径粘进去，重启VSCode，python --version就能生效了。

1.2 VSCode的Python插件只是语言服务，解释器得你亲手指定

VSCode装完Python扩展后，你打开一个.py文件，右下角会显示当前解释器路径。如果显示的是全局Python，而且你创建虚拟环境后VSCode还固执地指向老的解释器，那pip install装到虚拟环境里的包，VSCode运行时根本找不到——因为它是用全局环境跑的代码。

正确的做法是：按Ctrl+Shift+P，输入“Python: Select Interpreter”，在弹出的列表里找到当前项目虚拟环境下的python.exe。我见过太多人忽略这一步，后面疯狂pip install却始终报错，排查到最后发现是解释器指错了。

1.3 虚拟环境：打包最大的“后悔药”

不管你是刚开始学，还是已经写了好几个项目，都建议从最开始就养成“每个项目一个虚拟环境”的习惯。Windows下创建虚拟环境很简单：

bash复制python -m venv venv

然后激活它（Windows PowerShell或CMD）：

bash复制venv\Scripts\activate

命令行前面出现(venv)就说明当前激活了虚拟环境。之后安装的依赖都会进venv目录，不会污染全局环境。

为什么特别强调这个？因为打包exe时，工具会把当前环境里的依赖一起打包进去。如果你用的是全局环境，里面可能积累了几十个项目装过的包，PyInstaller会优先处理它能扫描到的模块，结果就是exe体积莫名其妙变大，或者干脆打包进一堆根本不需要的东西。用虚拟环境，打包的时候环境干净，exe体积小、不依赖的模块少、问题也好排查。

注意：激活虚拟环境这一步极其重要。很多人打包时发现用上了全局环境的包，或者pyinstaller命令找不到，多半是忘了在激活状态下打开VSCode终端。

2. 打包前的代码改造：为什么你的脚本一双击就闪退，问题其实出在源码上

2.1 入口文件与模块拆分的取舍

准备打包的第一件事，是整理好你的项目结构。最简单的场景是单文件脚本，比如main.py，直接打包没问题。但如果你的项目有多个模块，比如：

code复制my_project/
├── main.py
├── utils/
│   ├── __init__.py
│   ├── file_helper.py
│   └── db_manager.py
└── requirements.txt

打包时入口文件必须指向main.py，PyInstaller会从main.py开始分析import关系，把用到的模块自动收进去。没有被import到的文件，默认不会打包——所以千万别为了图省事把所有功能写在一个超大脚本里，拆成多个模块反而对打包更友好。

2.2 相对路径与绝对路径：exe最常见的静默杀手

写代码时，你多半用的是相对路径：

python复制with open("data.txt", "r", encoding="utf-8") as f:
    data = f.read()

这在源码运行环境没问题，因为工作目录就是项目文件夹。但打