Python 与虚拟环境
本合集目录
本章目录
单册说明:本文件是卷 5 的第 3 章,可独立阅读。前置:卷 0 第 4 章(装好 Python)、卷 1(终端基本操作)。本章只解决一件事:让每个项目的依赖互不干扰。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 5 · 后端与 API(第 3 / 8 章) |
| 前置章节 | 0.4 课前准备(Python 安装) |
| 本章产出 | 一个隔离的 .venv + 一份只用五行的 requirements.txt |
| 对应代码 | backend/requirements.txt、backend/.gitignore |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能解释"为什么我不能全局装",并能用两条命令自证隔离成功 |
5.3.1 一句话结论:pip install 装给"这台电脑",虚拟环境才装给"这个项目"
先看两个真实报错,它们其实是同一个原因。
第一个,在别人的机器上跑你的代码:
ModuleNotFoundError: No module named 'fastapi'
第二个,明明装了包,导入却失败:
ImportError: cannot import name 'field_validator' from 'pydantic'
第二条尤其迷惑:pydantic 装了啊。真相是装的是 1.x,而代码要 2.x——field_validator 是 2.x 才有的。
这两条都指向同一件事:Python 默认只有一个全局依赖目录,一个包同时只能存在一个版本。 你有两个项目、两种要求,它们就会互相踩。虚拟环境就是给每个项目发一个独立的抽屉。
5.3.2 原理与方法
全局安装到底装到了哪
C:\Users\你\AppData\Local\Programs\Python\Python313\Lib\site-packages\
你 pip install 的每一个包,都解压进这个目录。它有三个特征:
| 特征 | 后果 |
|---|---|
| 全机器共享 | 所有项目、所有脚本都用这一份 |
| 一个包只能一个版本 | 装新版本会覆盖旧版本,旧项目立刻坏 |
| 通常需要管理员权限 | 权限问题会伪装成"装不上" |
冲突现场长这样:
| 时间 | 你做了什么 | 结果 |
|---|---|---|
| 周一 | 项目 A 要 pydantic 1.x,装上,跑得好好的 |
全局里是 1.x |
| 周三 | 项目 B 要 pydantic 2.x,pip install -U pydantic |
全局变成 2.x |
| 周三下午 | 回去跑项目 A | AttributeError: 'Model' object has no attribute 'dict'(2.x 里改名了) |
于是你开始在两个项目之间反复升降级,一天就这么没了。这不是"你用得不对",是全局安装这个模型的必然结果。
venv 做了什么:不是复制 Python,是改优先级
python -m venv .venv 只做三件事:
| 动作 | 具体是什么 |
|---|---|
| 建目录 | .venv/ 下有 Scripts/(Windows)或 bin/、Lib/site-packages/、pyvenv.cfg |
| 放一个解释器入口 | Scripts/python.exe 是一个很小的启动器,启动时读 pyvenv.cfg 找到真正的 Python |
| 标记"我是虚拟环境" | pyvenv.cfg 里的 home = ... 指向基础安装 |
关键点:它没有复制标准库,也不会让 Python 变成另一个版本。 它只是让"找包"这一步先看 .venv/Lib/site-packages。
那"激活"又是什么?激活只是改环境变量,不是切换解释器。
| 激活时发生的事 | 你可以怎么验证 |
|---|---|
PATH 前面插入 .venv/Scripts |
Windows:where python;macOS/Linux:which python |
设置 VIRTUAL_ENV |
echo $VIRTUAL_ENV |
| 改命令行提示符前缀 | 你会看到 (.venv) |
所以"忘了激活"不是"没进虚拟环境",而是**"python 这个名字还指向全局那个"**。你完全可以不激活,用绝对路径直接调:
.venv/Scripts/python.exe -m pip list # Windows
.venv/bin/python -m pip list # macOS / Linux
这也是 CI 和脚本里的标准写法——明确指定解释器,比依赖"当前激活了哪个"可靠。
创建、激活、退出
| 系统 / 终端 | 创建 | 激活 | 退出 |
|---|---|---|---|
| Windows CMD | py -3 -m venv .venv |
.venv\Scripts\activate.bat |
deactivate |
| Windows PowerShell | py -3 -m venv .venv |
.venv\Scripts\Activate.ps1 |
deactivate |
| Windows Git Bash | py -3 -m venv .venv |
source .venv/Scripts/activate |
deactivate |
| macOS / Linux | python3 -m venv .venv |
source .venv/bin/activate |
deactivate |
两条实践规则:
- 虚拟环境目录固定叫
.venv,放在项目根目录。 不要叫venv,不要放家目录——固定名字让编辑器、.gitignore、别人接手时的操作全都一致。 - PowerShell 报"禁止运行脚本"时,不要改系统策略,改用 CMD 或 Git Bash 激活,或者直接用
.venv\Scripts\python.exe调。改执行策略是给整台机器开口子,代价远大于收益。
pip 与 requirements.txt:写"我要什么",不写"我当时有什么"
| 做法 | 写法 | 适合 | 风险 |
|---|---|---|---|
| 手写清单 | fastapi / uvicorn[standard] |
项目小、依赖少 | 别人装到的版本和你不同 |
| 下限约束 | fastapi>=0.110 |
需要新特性 | 上限打开,将来可能装到不兼容版本 |
pip freeze 全量快照 |
几十行带 == |
复现线上环境 | 会把无关包一起写进去 |
| 锁文件 | requirements.lock |
生产部署 | 需要工具生成,本书暂不引入 |
pip freeze 的坑很具体:它列出的是当前环境里所有包,包括你为了试验装过又忘了删的。更糟的是在有全局包的环境里执行它,会把整台机器的依赖都写进项目的清单。所以:
# 先确认自己在虚拟环境里
python -c "import sys; print(sys.prefix)"
# 再看清哪些是"你要的",哪些是"被带进来的"
pip list
本书的选择是手写五行清单:
fastapi
uvicorn[standard]
(uvicorn[standard] 是 extras 语法,表示"顺便装上性能相关的可选依赖"。)等以后真的需要精确复现,再引入锁文件——在第 3 章就上锁文件,属于用管理 50 人团队的流程管一个人的项目。
版本约束:五个符号够用了
requirements.txt 里除了包名,还可以写约束。写不写、怎么写,直接决定"半年后别人装到的是不是同一套":
| 写法 | 含义 | 什么时候用 |
|---|---|---|
fastapi |
不限版本,装最新的 | 学习期,追求省事 |
fastapi==0.115.0 |
精确锁定 | 复现线上环境、排查"升级后坏了" |
fastapi>=0.110 |
至少这个版本 | 需要某个新特性,但不介意更新 |
fastapi~=0.115.0 |
允许补丁位变化(0.115.x),次版本不动 |
想收安全补丁又不想被大改 |
fastapi<1.0 |
排除未来大版本 | 已知 1.0 会破坏兼容 |
一个真实的判断:报错里出现"我明明装的是最新的"时,先看约束。 有些人为了"稳定"把每个包都钉死到具体版本,结果三个月后想升级安全补丁,发现要手工解一张依赖网;另一些人完全不写约束,结果某天 pip install 装到了不兼容的新版本,代码没改却跑不起来。折中是:直接依赖写下限,部署时用锁文件钉死。
为什么本书只用 venv + pip
Python 的依赖管理工具不止一种,各有取舍:
| 工具 | 它多解决什么 | 为什么本书不用 |
|---|---|---|
venv + pip |
环境隔离、装包 | ——(本书用它) |
| conda | 同时管 Python 版本与非 Python 的二进制依赖(如科学计算库) | 多一层包源与概念,初学阶段排错更难 |
| poetry / pipenv | 锁文件、依赖分组、自动解析冲突 | 多一个配置文件与命令集,等你被依赖冲突折磨过再上 |
| uv 等新工具 | 安装速度、统一管理 Python 版本 | 生态较新,教程与报错资料少 |
这不是"别的工具不好",而是学习顺序:先用最朴素的方式把"隔离"这件事摸清楚,再去看任何工具,你都能一眼看出它在替你做什么。反过来,先用一个封装很厚的工具,出问题时你连"包被装到哪了"都答不上来。
"装不上"只有三类原因
分清这三类,比背任何命令都值钱:
| 类型 | 报错里的关键词 | 真实原因 | 修法 |
|---|---|---|---|
| 网络 | ReadTimeoutError、ETIMEDOUT、ProxyError、SSL: CERTIFICATE_VERIFY_FAILED |
连不上包服务器;公司代理;证书被拦 | 重试一次 → 配镜像源 → 给 pip 单独配代理 |
| 编译依赖 | error: Microsoft Visual C++ 14.0 or greater is required、gcc: command not found、Python.h: No such file |
这个包有 C 扩展,需要本地编译器 | 换有预编译包的版本;或装编译工具链;或选纯 Python 的替代品 |
| 版本冲突 | ResolutionImpossible、conflicting dependencies、requires X but you have Y |
两个包对同一个依赖要不同版本 | 看 pip 给出的冲突链,降/升其中一个;实在不行拆成两个环境 |
三条对应三种完全不同的动作。把第一类当第三类处理(去改版本号),是新手最常见的浪费。
py -3、python3、python:三个名字的来历
| 名字 | 哪来的 | 现状 |
|---|---|---|
python |
最早只有它 | Windows 上可能指向 Python 2、可能指向 3、也可能是微软商店的占位程序(运行后弹出商店) |
py -3 |
Windows 的启动器(py launcher) | 稳定指向最新的 Python 3,Windows 上首选 |
python3 |
macOS / Linux 的约定 | 这些系统上 python 可能是 2.7,所以必须写 3 |
判断方法不用记,直接问:
python -c "import sys; print(sys.version, sys.executable)"
输出里既有版本也有路径。看到路径是 WindowsApps 就是商店占位程序,去官网重装并勾选 Add to PATH。
5.3.3 动手:建环境、装包、自证隔离
在 ~/code/dudao/ 下:
mkdir -p backend && cd backend
py -3 -m venv .venv # macOS/Linux: python3 -m venv .venv
source .venv/Scripts/activate # Windows CMD: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install fastapi "uvicorn[standard]"
注意最后一行:"uvicorn[standard]" 要加引号或转义,因为 [ ] 在 bash 里有特殊含义(通配符)。不加引号偶尔能成,偶尔报 no matches found——这种"时好时坏"最难查。
验证一,看解释器指向哪:
python -c "import sys; print(sys.prefix)"
形如:
C:\code\dudao\backend\.venv
这就是隔离成功的第一个证据:sys.prefix 指向项目里的 .venv,不是 C:\Python313。
验证二,看装了哪些:
pip list
形如(版本号会变,结构不变):
Package Version
------------ -------
annotated-types 0.8.0
anyio 4.16.0
click 8.5.1
fastapi 0.163.1
h11 0.16.0
idna 3.20
pydantic 2.14.3
starlette 0.5x.x
uvicorn 0.54.0
只有十几个包,全是 FastAPI 的依赖。如果你看到几十上百个包,说明你在全局环境里——sys.prefix 会告诉你答案。
验证三,退出再对比:
deactivate
pip list | head -5
退出后 pip list 是新的一批(或报"没有 pip"),因为它换回了全局环境。同一台机器、两条命令、两个世界,这就是虚拟环境的全貌。
最后写 requirements.txt:
fastapi
uvicorn[standard]
以及 backend/.gitignore:
.venv/
__pycache__/
*.pyc
data/*.json
.venv 里通常有几千个文件、几十兆,而且跨平台不通用(Windows 的 .venv 拿到 Linux 上不能跑)。提交它等于给仓库塞垃圾。别人拿到项目后的动作永远是:
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
5.3.4 三个坑
坑一:忘了激活,包装到了全局
症状:装完 fastapi 显示成功,一运行就 ModuleNotFoundError: No module named 'fastapi';或者过几天另一个项目突然坏了。
成因:终端里 python 指向全局解释器,pip install 装进了全局 site-packages。等到你在虚拟环境里运行时,虚拟环境里当然没有它。
修法:养成两个习惯。① 开终端第一件事看提示符有没有 (.venv);② 一律用 python -m pip 而不是裸 pip——前者绑定"当前这个解释器",后者绑定"PATH 里第一个 pip",两者可能不是同一个。
坑二:把 .venv 提交进仓库
症状:git status 里几千个文件;git add . 卡住;仓库体积暴涨;换台机器 git pull 后依然跑不起来。
成因:虚拟环境里是编译好的二进制和绝对路径。Windows 的 .venv/Scripts/python.exe 到 Linux 上毫无意义。
修法:.gitignore 里加 .venv/,并且先加规则再建环境。已经提交了的话:git rm -r --cached .venv 再提交一次(历史里仍有,仓库不会变小,但至少不再新增)。真要让仓库变小只能重写历史——代价大到通常不值得,不如新建仓库。
坑三:在错误的目录启动服务
症状:
ERROR: Error loading ASGI app. Could not import module "app.main".
成因:uvicorn app.main:app 里的 app.main 是Python 的模块路径,从"当前工作目录"开始找。你在 backend/ 的上一级执行,它自然找不到 backend/app/main.py。
修法:先 pwd / cd 确认自己在 backend/,再启动。另一条更稳的路是加 --app-dir:
python -m uvicorn app.main:app --reload --app-dir backend
顺带说一句 --reload:它监视文件改动并自动重启,只用于开发。它的实现是起一个监视进程再拉子进程,在生产上会带来额外的内存与信号处理问题(卷 7 会用 systemd 管理进程,那里绝不加 --reload)。
本章验收
-
python -c "import sys; print(sys.prefix)"的输出指向项目里的.venv -
pip list里的包数量在二十个以内,且包含fastapi、uvicorn、pydantic - 执行
deactivate后,pip list的结果明显不同(证明两个环境独立) -
backend/requirements.txt只有两行,backend/.gitignore忽略了.venv/ - 能说出"装不上"的三类原因,并各举一个报错关键词
自测
Q1:为什么"激活虚拟环境"不是必须的?不激活会怎样?
看答案
激活的唯一作用是把 `.venv` 的 bin/Scripts 目录插到 PATH 最前面,让 `python`、`pip` 这些名字指向虚拟环境里的版本。它不改变文件、不改变已装的包。所以不激活也能用,只要写全路径(`.venv/Scripts/python.exe -m pip install ...`)。风险在于不激活时你输入的命令会悄悄作用于全局环境——命令成功返回,你以为装好了,实际装到了别处。CI 里通常不激活,就是因为写全路径更明确。Q2:pip freeze > requirements.txt 看起来最省事,为什么本书不用?
看答案
因为它记录的是"这台机器此刻的所有包",而不是"这个项目需要的包"。三个具体问题:① 试验时装过又忘删的包会被永久写进清单;② 如果环境不干净(混进了全局包),清单会膨胀成几十行;③ 它会把间接依赖也钉死,于是你永远不知道哪个是直接依赖,升级时无从下手。项目小时手写清单更清楚;需要精确复现时,用专门的锁文件工具生成,并保留一份"直接依赖"清单作为源。Q3:同事说"我这边 pip install fastapi 报 error: Microsoft Visual C++ 14.0 or greater is required,是不是网络问题?"
看答案
不是网络问题,是编译依赖问题。这个报错说明 pip 没找到预编译的 wheel,退回到从源码编译,而编译需要本地 C++ 工具链。三步处理:① 先升级 pip(新 pip 更能匹配到预编译包);② 确认 Python 版本不太新——刚发布的 Python 版本常常还没有对应的 wheel;③ 实在需要编译就装构建工具,但优先选前两条。网络问题的关键词是 timeout / reset / proxy,和这个报错完全不同类。下一步
环境干净了,可以开始写服务了。下一章故意不用框架,用标准库写五十多行——只有亲手写过路由匹配和读请求体,你才知道 FastAPI 到底替你省了什么。