跳到正文
零到全栈 · 卷 5 · 后端与 API

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 到底替你省了什么。

→ 卷5-04-手搓一个HTTP服务.md