venv 项目实战工作流:多版本 Python 与环境规范
上一篇我们把 venv 的创建、激活、依赖冻结都过了一遍,但真到了多人协作和长期维护的项目里,光会建环境还不够。最常见的翻车场景是这样的:组里新同事拉下代码,pip install -r requirements.txt 装了一半报错,查了半天发现他用的 Python 是 3.8,而项目要求 3.11;老员工机器上同时装着 3.9、3.10、3.12 四个版本,脚本跑起来调错了解释器,依赖装进了系统环境;还有人图省事把数据库密码、API 密钥直接写在代码里提交进了仓库,等发现时已经进了 Git 历史,想删都删不干净。
这些问题本质上都不是技术难题,而是没有规范。这篇就把 venv 在真实项目里的整套工作流立起来:一台机器管理多个 Python 版本、每个项目一个 .venv 的目录规范、.gitignore 该排除什么、密钥如何用 .env 管理、编辑器和脚本如何始终指向项目解释器、CI 和部署脚本如何从零还原环境,最后给一份可以直接抄进 README 的环境搭建模板。把这套规范定下来,新人入职、换机器、换服务器,都只需要照着做,不再靠口头传帮带。
前置条件
开始之前,先确认手头环境满足下面几点,后文所有命令都基于这个前提:
- 机器上至少装有一个可用的 Python 3 版本,能在终端里执行
python3 --version(Linux/macOS)或py --version(Windows)。 - 理解 venv 的基本用法:知道
python -m venv .venv建环境、激活脚本在哪、pip freeze > requirements.txt是干什么的。如果这些还不熟,先看本系列前面的 venv 入门篇。 - 项目用 Git 管理,并且仓库里已经有(或即将新建)
.gitignore文件。 - 示例项目统一叫
demo-app,目录结构和路径都是通用占位,你把名字换成自己的项目即可。
后文命令分 Windows 和 Linux 两套写。Windows 侧默认使用 python.org 官方安装包自带的 py 启动器,Linux 侧默认发行版自带或通过软件源安装的 python3.x 命令。两个平台的规范思想完全一致,只是调用解释器的方式不同。
一台机器装多个 Python 版本
为什么会需要多版本
理想情况当然是全公司统一一个版本,但现实是:老项目跑在 3.8 上不敢动,新项目想用 3.11 的新特性,某个数据处理脚本又依赖只支持到 3.10 的库。多版本共存是常态,关键是共存而不打架。venv 的隔离前提是「建环境时用对解释器」——用哪个版本的 Python 执行 -m venv,建出来的环境就是哪个版本。所以多版本管理的核心只有一件事:在任何时刻,都能准确地喊出你想要的那个解释器。
Windows:用 py 启动器点名版本
Windows 上从 python.org 下载的官方安装包会顺带安装一个 py 启动器(py launcher)。它的作用就是当你装了多个 Python 时,按版本号帮你找到对应的解释器。装新版本时记得勾选安装界面的「py launcher」选项(默认勾选),装完后先列一下机器上到底有哪些版本:
py -0p
输出类似下面这样,每一行是一个已安装版本及其解释器路径,带星号的是默认版本:
-V:3.12 * C:\Users\dev\AppData\Local\Programs\Python\Python312\python.exe
-V:3.11 C:\Users\dev\AppData\Local\Programs\Python\Python311\python.exe
-V:3.9 C:\Users\dev\AppData\Local\Programs\Python\Python39\python.exe
有了这个清单,建环境时直接点名版本即可。比如项目要求 3.11,就明确用 3.11 的解释器来建 .venv,不要用裸的 python -m venv——裸 python 指向谁取决于 PATH 顺序,换台机器结果可能完全不同:
cd C:\work\demo-app
py -3.11 -m venv .venv
.venv\Scripts\python.exe --version
最后一行是验证:直接调用环境内的解释器问版本号,确认建出来的确实是 3.11。日常运行脚本同理,临时跑某个版本的一次性命令用 py -3.9 xxx.py 这种写法,比改 PATH、改默认版本安全得多。需要提醒的是,py 启动器是 python.org 官方安装包提供的,微软商店版或某些第三方发行版不一定带它;如果 py -0p 提示命令不存在,优先从 python.org 装官方包。
Linux:用带版本号的命令名
Linux 没有统一的启动器,它的约定更直接:解释器命令本身带版本号。python3 是个泛称,具体版本是 python3.9、python3.11 这样的命令,多个版本可以并存于 /usr/bin 下互不干扰。先盘点一下机器上有什么:
ls /usr/bin/python3.* 2>/dev/null; ls /usr/local/bin/python3.* 2>/dev/null
python3.11 --version
python3.9 --version
建环境时同样点名版本,不要用含糊的 python3 -m venv:
cd ~/work/demo-app
python3.11 -m venv .venv
.venv/bin/python --version
如果发行版自带的版本不够新,Ubuntu/Debian 系可以考虑 deadsnakes PPA 这类第三方源补装新版本,RHEL 系可以用发行版的应用流模块或自行编译;具体安装方式各发行版差异较大,这里不展开,只强调一条原则:多装几个版本没关系,但不要去改系统默认的 python3 指向。系统工具、包管理器可能依赖默认版本,改了容易把系统搞坏。项目要哪个版本,就在命令里写死哪个版本。
每项目一个 .venv:目录规范与命名
版本点名解决的是「用谁建」,接下来是「建在哪、叫什么」的规范。推荐全团队统一下面这套约定,简单且和主流工具默认行为一致:
- 位置固定在项目根目录,不放
/opt、不放用户主目录、不和别的项目共用。环境跟着项目走,删项目时环境一起删,找的时候永远在同一个地方。 - 名字统一叫
.venv。带点的隐藏目录不会干扰代码浏览,VS Code、PyCharm 等编辑器也会自动探测名为.venv的环境并提示选用,省去手动配置。不要一会儿叫venv、一会儿叫env、一会儿叫项目名缩写——工具默认探测名单里通常包含.venv和venv,但团队内部只保留一个名字,文档和脚本才能写死路径。 - 一个项目只建一个环境。不要在同一个项目里并存
.venv和.venv-bak、.venv-old这种历史遗迹,环境坏了就整个删掉重建,反正有requirements.txt在,重建是分钟级的事。 - 环境不可移植。不要把
.venv拷给同事、打进发布包、或者从 Windows 拷到 Linux——环境里写死了本机路径和平台相关的二进制,拷过去多半是坏的。传递的永远应该是requirements.txt,环境在目标机器上现建。
一个规范的项目目录长这样,环境、依赖清单、密钥文件各就其位:
demo-app/
├── .venv/ # 虚拟环境,不进 Git
├── .env # 本机密钥配置,不进 Git
├── .env.example # 密钥模板,进 Git
├── .gitignore
├── requirements.txt # 依赖清单,进 Git
├── README.md
└── app/
└── main.py
.gitignore:必须排除什么
.gitignore 是这套规范里最不能省的一环。它要挡住两类东西:一是体积大且可重建的 .venv 和缓存目录——一个环境动辄几百 MB,提交进仓库会让每次克隆都痛苦不堪;二是装着真实密钥的 .env——这一条是安全红线,下面单独讲。项目根目录的 .gitignore 至少要有这几行:
# 虚拟环境
.venv/
venv/
# Python 缓存与构建产物
__pycache__/
*.py[cod]
*.egg-info/
build/
dist/
# 本机配置与密钥
.env
# 编辑器与系统杂项
.idea/
.vscode/
.DS_Store
几个容易踩的细节:第一,.venv/ 末尾的斜杠表示只匹配目录,没问题;第二,__pycache__ 不写全路径时能匹配任意层级的同名目录,正是想要的效果,因为每个包目录下都会生成它;第三,规则要在第一次提交之前就写好。如果 .venv 已经被提交进仓库了,事后补 .gitignore 不会让 Git 自动停止跟踪,还需要执行 git rm -r --cached .venv 把它从索引里移除再提交一次。.env 如果曾经进过仓库更麻烦,见下一节。
环境变量与密钥管理:.env 文件
铁律:密钥不进代码
先把话说死:数据库密码、API 密钥、Token 这类敏感信息,永远不要写在代码里,永远不要提交进 Git。原因有二。其一,代码是要到处流转的——进仓库、被打包、发给外包、贴到工单里排障,写死在代码里的密钥等于跟着代码到处跑。其二,Git 是有历史的,就算你今天发现写错了、改掉再提交,旧提交里的密钥依然躺在历史记录中,任何能拉仓库的人都能翻出来。真发生了密钥进仓库的事故,正确处置不是删代码,而是立刻去对应平台吊销并重新生成这个密钥,因为它必须被视为已经泄露。
正确做法是:密钥放在项目根目录的 .env 文件里(已在 .gitignore 中排除),代码运行时从环境变量读取。仓库里只提交一份不含真实值的 .env.example 模板,列出需要哪些变量,新人照着填自己的值。
.env 与 .env.example 的写法
.env.example 进 Git,长这样——只有键名和占位符,不带任何真实信息:
# 复制本文件为 .env,并填入真实值
DATABASE_URL=postgres://user:YOUR_PASSWORD@127.0.0.1:5432/demo
API_KEY=YOUR_API_KEY
DEBUG=true
每个开发者在自己机器上复制一份改名 .env,填入本机或自己申请的真实值;服务器上的 .env 由部署流程或运维单独放置,同样不经过 Git。这样同一个变量名,三套环境(开发、测试、生产)各填各的值,代码一行不用改。
代码里用 python-dotenv 读取
Python 进程不会自动加载 .env 文件,需要借助 python-dotenv 这个小库(把它写进 requirements.txt)。在程序入口最开头调用 load_dotenv(),它会把 .env 里的键值对注入到进程的环境变量中,之后用标准库 os.environ 读取即可:
import os
from dotenv import load_dotenv
load_dotenv() # 读取项目根目录的 .env
DATABASE_URL = os.environ["DATABASE_URL"] # 必填项:缺失直接报错,早暴露
API_KEY = os.environ.get("API_KEY", "") # 可选项:给默认值
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
两个习惯值得养成:一是必填项用 os.environ["KEY"] 的下标写法,缺失时启动即报错并指出缺哪个变量,好过运行到一半才神秘失败;二是布尔、数字类变量读出来都是字符串,要在读取处当场转换成目标类型,不要在业务代码里散落一堆字符串比较。另外注意 load_dotenv() 默认不覆盖系统里已经存在的同名环境变量,这正好符合部署习惯:服务器上由 systemd、Docker 或 CI 注入的真实环境变量优先级高于 .env 文件,本地开发才靠文件兜底。
让编辑器和脚本始终用对解释器
环境建好了,还要保证「跑代码的每一处入口」都指向它。入口无非三类:编辑器运行、终端手动执行、脚本和定时任务自动执行,逐个说。
编辑器:选一次,记在工作区里
VS Code 里用命令面板执行「Python: Select Interpreter」,选中项目下 .venv 里的解释器。这个选择会写进工作区的 .vscode/settings.json,生成类似 "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"(Linux 是 .venv/bin/python)的配置。是否把 .vscode 提交进仓库各团队习惯不同,但至少本机选过一次之后,编辑器里的运行、调试、测试都会走项目环境,不会再串到系统 Python。PyCharm 同理,在解释器设置里添加已存在的 .venv 环境并设为项目解释器。
终端与脚本:能写全路径就别依赖激活
激活环境(Windows 的 .venv\Scripts\Activate.ps1、Linux 的 source .venv/bin/activate)是给人在终端里交互用的,方便但脆弱:新开窗口忘了激活、脚本被计划任务拉起时没人激活,都会跑偏。给团队的建议是:交互终端里随便激活,但在任何要留档、要复用的脚本里,直接写环境内解释器的全路径。比如 Windows 的批处理或 PowerShell 脚本里写 .venv\Scripts\python.exe app\main.py,Linux 的 shell 脚本和 crontab 里写 /home/dev/demo-app/.venv/bin/python /home/dev/demo-app/app/main.py。全路径不依赖当前目录、不依赖激活状态,谁在什么环境下执行结果都一致。顺带一提,往环境里装包也一样,.venv/bin/python -m pip install xxx 永远比裸 pip install 靠谱,因为后者装到哪个环境取决于 PATH 里排第一的是谁。
CI 与部署:从零还原环境的标准三行
前面所有规范,最终都要在 CI 和部署环节收口。还原环境的动作请在全团队统一成下面这「三行」——指定版本建环境、用环境内的 pip 装依赖、(按需)校验版本。Linux 侧:
python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python --version
Windows 侧把第一行换成 py -3.11 -m venv .venv,后两行把 .venv/bin/python 换成 .venv\Scripts\python.exe,其余完全一致。这三行要原样出现在 CI 配置、部署脚本和 README 里,不允许各写各的变体。它能成立的前提正是前面的规范都落实了:版本写死所以不会建错,依赖全在 requirements.txt 里所以一次装齐,密钥走环境变量或 .env 所以 CI 平台在自己的密钥配置里注入、不用改脚本。
CI 里还有两个细节。一是依赖文件必须在本地用 pip freeze 冻结出确切版本再提交,CI 装的是冻结清单而不是一句含糊的 pip install flask,否则今天和下周装出来的版本可能不同,构建不可复现。二是如果项目对 Python 版本有硬性要求,可以在 CI 第一步就加版本断言,版本不对立刻失败并给出清晰报错,而不是等到装依赖时抛一堆看不懂的错。
README 模板:把环境搭建写清楚
规范的最后一公里是文档。新人加入项目时,唯一应该看的就是 README 里的「环境搭建」一节。把下面这段模板放进每个项目的 README,按项目实际情况改版本号和启动命令即可:
## 环境搭建
本项目要求 Python 3.11,其他版本未做兼容测试。
### 1. 创建虚拟环境(在项目根目录执行)
Windows:
py -3.11 -m venv .venv
Linux / macOS:
python3.11 -m venv .venv
### 2. 安装依赖
Windows:
.venv\Scripts\python.exe -m pip install -r requirements.txt
Linux / macOS:
.venv/bin/python -m pip install -r requirements.txt
### 3. 配置环境变量
复制 .env.example 为 .env,按注释填入本机的值(向组长索取测试环境密钥)。
.env 已加入 .gitignore,禁止提交真实密钥。
### 4. 启动
.venv/bin/python -m app.main # Windows 换成 .venv\Scripts\python.exe
模板虽短,但把后人会卡住的点全堵上了:版本要求、双平台命令、密钥从哪来、怎么启动。维护成本也很低——升级 Python 版本时改这一节,顺手改 CI 里的三行,仅此而已。比起在群里反复回答「你 Python 版本多少」,这十几行字省下的时间不可估量。
验证:新环境是否规范
随便找一台干净机器(或把本机项目的 .venv 删掉),按 README 从头走一遍,能全部通过下面这份清单,就算规范落地了:
- 删除
.venv后,仅按 README 三步即可重建环境并成功启动项目,全程不需要问任何人。 .venv/bin/python --version(Windows 为.venv\Scripts\python.exe --version)输出的版本与 README 要求一致。git status里看不到.venv/、__pycache__/和.env被列为待提交文件;git ls-files | grep -E "^\.env$|\.venv"无输出,说明它们从未进过仓库。- 代码里全文搜索
password、api_key等关键词,命中的应该只有从os.environ读取的那几行,没有任何写死的真实值。 - 编辑器状态栏显示的解释器指向项目
.venv,在编辑器里直接运行入口文件不报缺包。
常见问题
py -0p 只列出一个版本,但我明明装了两个
多半是另一个版本不是从 python.org 装的(比如微软商店版或被其他软件捆绑安装),没有向 py 启动器注册。用官方安装包重装一次目标版本即可,安装时保持默认选项,启动器会自动识别。
Linux 上 python3.11 -m venv 报错,提示缺 ensurepip 或 venv 模块
Debian/Ubuntu 把 venv 支持拆成了独立包,需要先装 sudo apt install python3.11-venv(版本号与目标版本对应)。这是发行版的打包方式问题,不是你命令写错了,报错信息里通常也会直接给出这个提示。
同事说他激活了环境,但 pip list 还是不对
先让他执行 which python(Linux)或 where python(Windows)确认当前终端实际调用的是不是 .venv 里的解释器。十有八九是开了新终端忘了重新激活,或者机器上同名环境太多激活错了项目。这也是为什么脚本里一律推荐写解释器全路径——不依赖激活状态,没有这种 ambiguity。
.env 已经被提交进仓库了,删掉重新提交行吗
不够。删掉只是让最新版本里没有它,历史提交里依然能翻出来。正确处置是:第一,立即吊销并重新生成里面出现过的所有密钥,按已泄露处理;第二,再把文件从当前版本移除并加入 .gitignore;第三,如有必要用历史重写工具清理仓库并强制推送,同时通知所有协作者重新克隆。顺序不能反,吊销密钥永远是第一步。
能不能全组共用一个建在共享目录的环境,省得每人建
不建议。共用环境意味着任何一个人装包、升级都会影响所有人,出问题无法追责;而且环境里写死的是创建时的机器路径,换台机器就不可用。每项目在本机建自己的 .venv、靠 requirements.txt 保证一致,才是可扩展的做法。磁盘占用在如今的开发机上不是问题。
小结
这篇讲的其实都不是高深技术,而是一组互相咬合的约定:用 py -0p 或带版本号的命令点名解释器解决多版本共存;每个项目根目录放一个统一命名的 .venv,环境只靠 requirements.txt 重建、从不拷贝传递;.gitignore 在第一次提交前就排除 .venv、__pycache__ 和 .env;密钥一律进 .env 并用 python-dotenv 读取,仓库里只留 .env.example 模板;编辑器选好项目解释器、脚本里写解释器全路径;CI 和部署统一用「建环境、装依赖、验版本」三行还原;最后把这一切浓缩进 README 的环境搭建一节。规范的价值不在文档本身,而在于它让「换一台机器、换一个人」都不再成为事故的起点。下一次新建 Python 项目时,花十分钟把这套东西铺好,后面省下的是无数个十分钟。







