侧边栏壁纸
博主头像
我的博客站

  • 累计撰写 112 篇文章
  • 累计创建 4 个标签
  • 累计收到 0 条评论

目 录CONTENT

文章目录
Python

Python(三十九) 虚拟环境与 pip 依赖管理完整教程

Python(三十九) 虚拟环境与 pip 依赖管理完整教程

目录

  1. 开篇：为什么需要虚拟环境？
  2. venv：Python 自带的虚拟环境工具
  3. virtualenv：第三方的增强版虚拟环境工具
  4. pip 核心基础用法
  5. requirements.txt 依赖清单全流程
  6. 依赖管理与版本控制规范
  7. pip 升级与镜像源配置
  8. 进阶工具：pipx / poetry / pipenv
  9. 常见报错排查手册
  10. 最佳实践 15 条
  11. 课后实操作业

一、开篇：为什么需要虚拟环境？

1.1 生活化类比

想象你是一个化学老师，手上有三个实验班：

  • A 班做实验需要"烧杯"和"试管"（版本 2024 款）
  • B 班做实验需要"烧杯"和"试管"（版本 2023 款，因为 2024 款和他们的某种试剂不兼容）
  • C 班压根不需要"烧杯"，但需要"显微镜"

如果你把三个班的器材全部堆在同一个实验室里（全局环境），会发生什么？

  • 烧杯只能有一个版本，A 班和 B 班总有一个出问题
  • C 班的桌子上多了一堆用不上的器材，乱糟糟的

虚拟环境就是给每个实验班分配一个独立的储物柜——每个班从自己的柜子里拿器材，互不干扰。

1.2 编程中的"器材冲突"

在 Python 编程中，"器材"就是第三方库（也叫"包"或"依赖"）。

全局环境安装依赖 → 所有项目共享同一个 Python 环境

项目 A：需要 requests==2.20.0  ─┐
                                ├── 冲突！只能装一个版本！
项目 B：需要 requests==2.31.0  ─┘

# 场景：你在全局 Python 环境里装了 Flask 2.0
# pip install flask==2.0.0

# 过了几天，你接手了一个老项目，它需要 Flask 1.1
# 你不得不卸载 2.0 装 1.1
# pip uninstall flask
# pip install flask==1.1.4

# 结果你之前写的 Flask 2.0 项目跑不起来了……
# 这就是"依赖地狱"的缩影

1.3 虚拟环境是怎么解决的？

项目 A/                          项目 B/
├── venv/  (独立的 Python 环境)    ├── venv/  (独立的 Python 环境)
│   └── requests==2.20.0           │   └── requests==2.31.0
├── main.py                        ├── main.py

两个项目的 venv 完全隔离，互不干扰！

虚拟环境本质上就是一个"文件夹"——它包含了一份独立的 Python 解释器副本和独立的包安装目录。你在虚拟环境里装包，完全不会影响全局环境和其他虚拟环境。

特性 全局环境 虚拟环境
包裹安装位置 全局 site-packages 项目文件夹内的 site-packages
多项目版本冲突 会冲突 不会冲突
环境可复刻 困难 用 requirements.txt 轻松复刻
换电脑/重装系统 需要重新装所有包 用 requirements.txt 一键安装
污染风险 高（装多了不知道哪些在用） 低（每个项目只装自己需要的）

1.4 学完本教程你将能够

  1. 用 venv 和 virtualenv 创建、激活、管理虚拟环境
  2. 用 pip 安装、卸载、查看、升级 Python 包
  3. 用 requirements.txt 管理项目依赖，实现环境一键复刻
  4. 配置国内镜像源，解决下载慢的问题
  5. 处理常见的依赖冲突和环境问题
  6. 了解 pipx、poetry 等现代工具的用法

二、venv：Python 自带的虚拟环境工具

2.0 环境准备

venv 是 Python 3.3+ 自带的模块，不需要额外安装。

先确认你的环境没问题：

# 第一步：确认 Python 已正确安装
python --version
# 预期输出：Python 3.9.x 或更高版本

# 第二步：确认 pip 可用
pip --version
# 预期输出：pip 24.x from C:\... (python 3.9)

# 如果以上命令提示"不是内部命令"，说明 Python 没添加到系统 PATH
# 解决方法：重新安装 Python，勾选 "Add Python to PATH"

2.1 创建虚拟环境

# 通用语法（Windows 和 Mac/Linux 一样）
python -m venv 虚拟环境名称

# 示例：创建一个名为 myenv 的虚拟环境
python -m venv myenv

# 执行后，当前目录下会出现一个 myenv 文件夹
# 这个文件夹就是你的虚拟环境，大小约 10-20MB

命名惯例：虚拟环境通常叫 venv、env、.venv（点开头在 Linux 上是隐藏文件夹），项目中最常见的命名是 venv。

2.2 激活虚拟环境

激活后，你在终端里安装的所有 Python 包都会进入这个虚拟环境，而不是全局环境。

Windows（PowerShell）

# PowerShell
myenv\Scripts\Activate.ps1

# 可能的报错：执行策略限制
# 报错信息：无法加载文件...因为在此系统上禁止运行脚本
# 解决方法：以管理员身份运行 PowerShell，执行：
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 然后重新激活

Windows（CMD）

:: 命令提示符（CMD）
myenv\Scripts\activate.bat

Mac / Linux

# Mac / Linux
source myenv/bin/activate

2.3 怎么知道激活成功了？

看终端提示符： 激活成功后，终端提示符前面会出现 (虚拟环境名称)。

# 激活前
C:\Users\用户名\project>

# 激活后（注意前面的 (myenv)！）
(myenv) C:\Users\用户名\project>

再确认一下 Python 的位置：

# 激活虚拟环境后
where python    # Windows
# 或
which python    # Mac / Linux

# 输出应该指向虚拟环境内的 python
# Windows: C:\Users\...\project\myenv\Scripts\python.exe
# Linux:   /home/.../project/myenv/bin/python

# 再确认 pip 的位置
where pip       # Windows
which pip       # Mac / Linux
# 同样应该指向虚拟环境内的 pip

2.4 退出虚拟环境

# 所有平台通用
deactivate

# 执行后，终端提示符前面的 (myenv) 会消失
# 此时 pip 和 python 回到全局环境

2.5 删除虚拟环境

# 虚拟环境就是一个文件夹，删除它即可
# Windows:
rmdir /s myenv

# Mac / Linux:
rm -rf myenv

# 注意：删除前确保虚拟环境已退出（执行 deactivate）

2.6 虚拟环境文件夹内部结构

myenv/                         ← 虚拟环境根目录
├── pyvenv.cfg                 ← 配置文件（记录了 Python 版本等信息）
├── Lib/                       ← Python 标准库 + 已安装的第三方库
│   └── site-packages/         ← ★ 你 pip install 的包都装在这里
│       ├── flask/
│       ├── requests/
│       └── ...
├── Scripts/                   ← Windows：可执行文件目录
│   ├── python.exe             ← 虚拟环境专属的 Python 解释器
│   ├── pip.exe                ← 虚拟环境专属的 pip
│   ├── activate.bat           ← CMD 激活脚本
│   └── Activate.ps1           ← PowerShell 激活脚本
└── Include/                   ← C 扩展头文件（一般不用管）

核心理解：

  • Scripts/python.exe（Windows）或 bin/python（Linux）= 这个虚拟环境的专属 Python
  • Lib/site-packages/ = 虚拟环境里装的所有包都在这里
  • 激活的本质 = 把 Scripts/ 或 bin/ 临时加到系统的 PATH 最前面

避坑 1：虚拟环境文件夹不要改名、不要移动，否则激活脚本会失效。如果必须移动，删了重建。

避坑 2：不要用 cmd 的 activate.bat 在 PowerShell 中执行，反之亦然。

避坑 3：虚拟环境激活后，用 pip install 装包时不要加 sudo（Linux/Mac），否则可能装到全局环境。

课堂小练习 1

  1. 在你的工作目录下，用 python -m venv test_env 创建一个虚拟环境
  2. 激活它，观察终端提示符的变化
  3. 执行 where python（Windows）或 which python（Mac/Linux），确认当前使用的是虚拟环境的 Python
  4. 执行 deactivate 退出，再执行一遍上面的命令确认路径变化
  5. 最后删除 test_env 文件夹

验收标准：你能清楚地分辨终端是否处于虚拟环境中，知道如何激活和退出。

三、virtualenv：第三方的增强版虚拟环境工具

3.1 为什么还需要 virtualenv？

特性 venv virtualenv
是否需要安装 否（Python 3.3+ 内置） 需要 pip install virtualenv
Python 2 支持 不支持 支持
指定 Python 版本 不支持 支持
速度 快 稍慢（功能更多）
自定义程度 较低 高

简而言之：如果你只用 Python 3.6+，用 venv 就够了。如果需要 Python 2 兼容，或者想指定特定版本的 Python 解释器来创建环境，用 virtualenv。

3.2 安装 virtualenv

# 先安装 virtualenv（建议装在全局环境）
pip install virtualenv

# 确认安装成功
virtualenv --version
# 预期输出：virtualenv 20.x.x

3.3 基本操作（和 venv 几乎一样）

# 创建虚拟环境
virtualenv myenv

# 激活（和 venv 完全一样）
# Windows PowerShell: myenv\Scripts\Activate.ps1
# Windows CMD:       myenv\Scripts\activate.bat
# Mac / Linux:       source myenv/bin/activate

# 退出
deactivate

3.4 高级用法

指定 Python 版本创建虚拟环境：

# 场景：电脑上同时装了 Python 3.9 和 Python 3.11
# 你想用 Python 3.9 创建虚拟环境

# 先找到 Python 3.9 的完整路径
# Windows: C:\Python39\python.exe
# Linux:   /usr/bin/python3.9
# 或直接用 py 启动器（Windows）

# 指定路径创建
virtualenv -p C:\Python39\python.exe myenv_py39

# 或：指定版本号（前提是 python3.9 在 PATH 中）
virtualenv -p python3.9 myenv_py39

# 确认版本
myenv_py39\Scripts\activate   # 激活后
python --version               # Python 3.9.x

创建完全隔离的虚拟环境：

# 默认情况下，virtualenv 会让虚拟环境访问全局已安装的包
# 加上 --no-site-packages 完全隔离（现在已是默认行为）
virtualenv --no-site-packages myenv

# 反过来，如果想继承全局包（不推荐）
virtualenv --system-site-packages myenv

3.5 virtualenvwrapper：批量管理虚拟环境

如果你经常在多个项目间切换，每次都要 cd 到项目目录再激活，很麻烦。virtualenvwrapper 把所有虚拟环境集中管理。

# 安装（Windows 用 virtualenvwrapper-win）
# Windows:
pip install virtualenvwrapper-win

# Mac / Linux:
pip install virtualenvwrapper
# 还需要在 ~/.bashrc 或 ~/.zshrc 里加：
# export WORKON_HOME=$HOME/.virtualenvs
# source /usr/local/bin/virtualenvwrapper.sh


# 创建虚拟环境（统一放在 ~/.virtualenvs/ 下）
mkvirtualenv project_a
mkvirtualenv project_b

# 列出所有虚拟环境
lsvirtualenv

# 激活虚拟环境（可以在任意目录执行，不用 cd！）
workon project_a

# 退出
deactivate

# 删除虚拟环境
rmvirtualenv project_a
工具 适用场景
venv Python 3.3+ 用户，简单项目，内置于 Python 无需安装
virtualenv 需要 Python 2 支持，或需要指定不同 Python 版本
virtualenvwrapper 管理 5 个以上虚拟环境，希望集中管理

课堂小练习 2

  1. 安装 virtualenv：pip install virtualenv
  2. 用 virtualenv 创建一个名为 v_env 的虚拟环境，激活它，确认 Python 版本
  3. （选做）安装 virtualenvwrapper-win（Windows）或 virtualenvwrapper（Mac/Linux），练习 mkvirtualenv、workon、lsvirtualenv 命令

验收标准：能分别用 venv 和 virtualenv 创建虚拟环境，清楚两者的区别。

四、pip 核心基础用法

4.0 pip 是什么？

pip 是 Python Install Package 的缩写，是 Python 官方推荐的包管理工具。它连接着 PyPI（Python Package Index，Python 包索引网站），你可以把它理解为"Python 的应用商店"。

生活类比：pip 就像手机的"应用商店"。你说 pip install 微信，它就自动下载安装好，还帮你搞定所有依赖。

4.1 包的安装

# 安装最新版本
pip install requests

# 输出示例：
# Collecting requests
#   Downloading requests-2.31.0-py3-none-any.whl (62 kB)
# Collecting urllib3<3,>=1.21.1
#   Downloading urllib3-2.0.7-py3-none-any.whl (124 kB)
# Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests
# Successfully installed certifi-2024.x charset-normalizer-3.x idna-3.x requests-2.31.0 urllib3-2.0.7

指定版本安装：

# 安装指定版本
pip install requests==2.28.0

# 安装最低版本
pip install "requests>=2.28.0"

# 安装版本范围
pip install "requests>=2.25.0,<2.30.0"

# 安装最新版本（默认行为）
pip install requests

# 升级到最新版本
pip install --upgrade requests
# 或简写
pip install -U requests

4.2 包的查看

# 列出已安装的所有包
pip list

# 输出示例：
# Package            Version
# ------------------ --------
# certifi            2024.8.30
# charset-normalizer 3.3.2
# flask              3.0.0
# pip                24.2
# requests           2.31.0
# ...

# 查看某个包的详细信息
pip show requests

# 输出示例：
# Name: requests
# Version: 2.31.0
# Summary: Python HTTP for Humans.
# Home-page: https://requests.readthedocs.io
# Author: Kenneth Reitz
# License: Apache 2.0
# Location: C:\...\myenv\Lib\site-packages        ← 安装位置
# Requires: certifi, charset-normalizer, idna, urllib3  ← 依赖的其他包
# Required-by: flask                                ← 哪些包依赖了它

# 检查哪些包已过时（有更新版本）
pip list --outdated

# 输出示例：
# Package    Version    Latest    Type
# ---------- ---------- ---------- -----
# requests   2.28.0     2.31.0    wheel

4.3 包的搜索（线上查找）

# 在线搜索包（部分新版 pip 可能不支持 search 命令）
pip search 包名

# 如果 pip search 不可用或被禁用：
# 替代方案：直接访问 PyPI 官网搜索
# https://pypi.org/search/?q=包名

# 或者在终端用以下方式替代：
# Windows:
python -c "import webbrowser; webbrowser.open('https://pypi.org/search/?q=flask')"

# 或者用 pip_search 第三方工具：
# pip install pip-search
# pip_search flask

4.4 包的卸载

# 卸载包
pip uninstall requests

# 会提示确认：
# Found existing installation: requests 2.31.0
# Uninstalling requests-2.31.0:
#   Would remove:
#     c:\...\myenv\lib\site-packages\requests-2.31.0.dist-info\*
#     c:\...\myenv\lib\site-packages\requests\*
# Proceed (Y/n)? y          ← 需要输入 y 确认
#   Successfully uninstalled requests-2.31.0


# 跳过确认提示，直接卸载
pip uninstall -y requests

# 注意：pip 只卸载你指定的包，不会自动卸载它的依赖
# 所以可能会留下"孤儿包"（没用了但还占着空间）

4.5 通用写法：python -m pip

# 问题场景：你的电脑上装了多个 Python 版本
# 直接写 pip install xxx 可能用的是错误的 pip

# 通用做法：用 python -m pip，确保 pip 和你想要的 Python 对应
python -m pip install requests    # 当前 python 对应的 pip

# 指定 Python 版本
python3.9 -m pip install requests  # Python 3.9 对应的 pip
python3.11 -m pip install requests # Python 3.11 对应的 pip

# 判断方法：python -m pip 一定和你刚执行的那个 python 是同一个环境
# 而直接 pip 可能对应 PATH 中最前面的那个 Python

避坑 1：多 Python 版本环境下，永远用 python -m pip 而不是裸 pip

避坑 2：在虚拟环境中，激活后直接写 pip 是安全的，因为 PATH 已经被虚拟环境接管

避坑 3：pip install 后加 --user 会把包装到用户目录而非虚拟环境，在虚拟环境中不要用

课堂小练习 3

  1. 激活一个虚拟环境，执行以下操作：
    • 安装 flask 和 requests
    • 用 pip list 查看已安装的包
    • 用 pip show flask 查看 flask 的详细信息
    • 卸载 requests，确认它从列表中消失
  2. （选做）尝试安装指定版本的包：pip install flask==2.0.3，观察 pip list 的版本变化

验收标准：能独立完成包的安装、查看、卸载全流程。

五、requirements.txt 依赖清单全流程

5.1 什么是 requirements.txt？

requirements.txt 是一个文本文件，列出了项目需要的所有 Python 包及其版本。它的核心作用是让任何人在任何电脑上都能一键还原你的开发环境。

生活类比：requirements.txt 就像"药方"。你去看中医，医生开的药方上写着"当归 10g、黄芪 15g、枸杞 5g"。你拿着这个药方去任何一家中药店，都能配出完全一样的药。requirements.txt 就是 Python 项目的"药方"。

5.2 生成 requirements.txt

# 在虚拟环境激活状态下执行
pip freeze > requirements.txt

# freeze 是什么？
# freeze = "冻结"——把当前环境中所有包的名称和版本"定格"下来

pip freeze vs pip list 的区别：

# pip list：人类可读的表格格式
# Package            Version
# ------------------ --------
# click              8.1.7
# flask              3.0.0
# ...

# pip freeze：机器可读的格式（包名==版本号）
# click==8.1.7
# flask==3.0.0
# ...

# 为什么用 pip freeze？
# freeze 输出的 "包名==版本号" 格式可以直接被 pip install -r 理解
# 而 pip list 的表格格式不行

生成后的 requirements.txt 长这样：

blinker==1.7.0
click==8.1.7
colorama==0.4.6
flask==3.0.0
itsdangerous==2.1.2
jinja2==3.1.3
markupsafe==2.1.5
werkzeug==3.0.1

5.3 基于 requirements.txt 安装依赖

# 在新的虚拟环境中，一键安装所有依赖
pip install -r requirements.txt

# 输出示例：
# Collecting flask==3.0.0
#   Downloading flask-3.0.0-py3-none-any.whl
# Collecting click==8.1.7
#   Downloading click-8.1.7-py3-none-any.whl
# ...
# Successfully installed click-8.1.7 flask-3.0.0 ...

安装失败的排查步骤：

  1. 版本不存在：某个包在 PyPI 上已经删除了该版本 → 修改为存在的版本号
  2. 网络问题：超时 → 换国内镜像源（见第七章）
  3. 平台兼容：有些包只支持特定操作系统 → 检查是否装了 Windows-only 的包到 Linux 上

5.4 进阶写法

# requirements.txt 的高级写法

# 1. 注释（用 # 开头）
# 这是项目的核心依赖
flask==3.0.0
requests==2.31.0

# 2. 指定版本范围
numpy>=1.24.0,<2.0.0     # 1.24 及以上，但不跨到 2.0

# 3. 不等于某个版本
click!=8.1.5              # 除了 8.1.5 都可以

# 4. 兼容版本（~=）
django~=4.2.0             # 4.2.0 <= 版本 < 4.3.0

# 5. 从 Git 仓库安装
# git+https://github.com/user/repo.git@分支名

# 6. 从本地 wheel 文件安装
# ./local_packages/my_package-1.0.0-py3-none-any.whl

dev 依赖拆分（推荐做法）：

项目/
├── requirements.txt          ← 生产环境（所有环境都需要）
└── dev-requirements.txt      ← 开发环境额外依赖（测试、格式化等）

# requirements.txt（精简——只放运行时必须的）
flask==3.0.0
requests==2.31.0

# dev-requirements.txt（开发时额外的）
-r requirements.txt       ← 先引用生产依赖
pytest==8.0.0
black==24.1.0
flake8==7.0.0

安装时：

# 生产环境：只装运行时依赖
pip install -r requirements.txt

# 开发环境：装全所有依赖
pip install -r dev-requirements.txt

课堂小练习 4（核心练习）

操作步骤：

  1. 创建一个全新的虚拟环境 env_a
  2. 激活后，安装 flask 和 requests
  3. 执行 pip freeze > requirements.txt 生成依赖清单
  4. 退出 env_a，再创建一个全新的虚拟环境 env_b
  5. 激活 env_b，执行 pip install -r requirements.txt
  6. 在 env_b 中执行 pip list，确认安装的包和 env_a 中一致

验收标准：你能在另一台电脑（或另一个虚拟环境）中通过 requirements.txt 复原完全相同的包环境。

六、依赖管理与版本控制规范

6.1 Python 包的版本号规范（语义化版本）

版本号格式：主版本号.次版本号.修订号（Semantic Versioning，简称 SemVer）

2  .  31  .  0
↑      ↑      ↑
主版本  次版本  修订号

例如：Flask 3.0.0
- 主版本 = 3    不兼容的大改动（API 变了，老代码可能跑不了）
- 次版本 = 0    加了新功能，但向后兼容（老代码还能跑）
- 修订号 = 0    Bug 修复，没有新功能

版本约束符号：

写法 含义 示例
==2.31.0 精确等于 必须是 2.31.0
>=2.31.0 大于等于 2.31.0 及以上都可以
<=2.31.0 小于等于 2.31.0 及以下都可以
!=2.31.0 不等于 除了 2.31.0 其他都行
>2.0,<3.0 范围 2.0.x 都可以，但不能到 3.0
~=2.31.0 兼容版本 >=2.31.0, <2.32.0（同主次版本号）

6.2 理解依赖冲突

场景：两个项目需要同一个包的不同版本

# 没有虚拟环境时：
# 项目 A 需要 flask 2.0
# 项目 B 需要 flask 3.0
# → 冲突！只能装一个版本

# 有虚拟环境时：
# 项目 A 在 venv_a 中装 flask 2.0
# 项目 B 在 venv_b 中装 flask 3.0
# → 不冲突，各自独立

场景：同一个虚拟环境内两个包冲突

# 假设你装了 package_x 和 package_y
# package_x 依赖 requests>=2.20.0
# package_y 依赖 requests<=2.19.0
# → pip 安装时会报错

# 检测依赖冲突
pip check

# 如果没问题：
# 输出：No broken requirements found.

# 如果有冲突：
# package_y 1.0.0 requires requests<=2.19.0, but you have requests 2.31.0

6.3 Git 版本控制规范

.gitignore 必须添加虚拟环境文件夹：

# Python 虚拟环境
venv/
env/
.venv/
ENV/
env.bak/
venv.bak/

# Python 缓存
__pycache__/
*.py[cod]
*.pyo

# IDE 配置
.vscode/
.idea/

团队协作的依赖同步流程：

开发者 A （开发新功能）：
1. 激活虚拟环境
2. pip install 新包
3. pip freeze > requirements.txt
4. git add requirements.txt
5. git commit -m "添加新依赖 xxx"
6. git push

开发者 B （拉取更新）：
1. git pull
2. 激活虚拟环境
3. pip install -r requirements.txt
4. 验证环境正常

核心原则：

  • requirements.txt → 提交到 Git（小文件，几 KB）
  • venv/ 文件夹 → 不提交（几十 MB，且依赖可以通过 requirements.txt 还原）
  • 不要提交 venv/ 文件夹到远程仓库，否则别人会收到几十 MB 的垃圾文件

七、pip 升级与镜像源配置

7.1 pip 自身升级

# 查看当前 pip 版本
pip --version

# 升级 pip 到最新版本
python -m pip install --upgrade pip

# Windows 如果提示权限不足：
# 以管理员身份运行终端，再执行上面的命令

# Linux / Mac 如果提示权限不足：
python -m pip install --upgrade pip --user

# 如果升级后 pip 出问题了，可以回退：
python -m pip install pip==24.0      # 换一个已知稳定版本

7.2 为什么需要镜像源？

PyPI 官方源在国外，国内下载速度极慢（几十 KB/s，甚至超时）。国内镜像源是 PyPI 的完整拷贝，下载速度可达 MB/s。

7.3 临时使用镜像源

# 单次安装使用清华镜像源
pip install flask -i https://pypi.tuna.tsinghua.edu.cn/simple

# 其他常用国内源：
# 清华源：  https://pypi.tuna.tsinghua.edu.cn/simple
# 阿里源：  https://mirrors.aliyun.com/pypi/simple/
# 豆瓣源：  https://pypi.douban.com/simple/
# 中科大源：https://pypi.mirrors.ustc.edu.cn/simple/

7.4 永久配置镜像源

Windows

  1. 在文件资源管理器地址栏输入 %APPDATA% 并回车
  2. 进入 pip 文件夹（没有就新建一个）
  3. 在 pip 文件夹中创建 pip.ini 文件
  4. 写入以下内容：
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

# 完整路径示例：
# C:\Users\你的用户名\AppData\Roaming\pip\pip.ini

Mac / Linux

# 创建配置文件目录
mkdir -p ~/.pip

# 编辑配置文件
nano ~/.pip/pip.conf

写入以下内容：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

7.5 验证镜像源配置

# 查看当前的 pip 配置
pip config list

# 预期输出：
# global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
# global.trusted-host='pypi.tuna.tsinghua.edu.cn'

# 安装一个包测试下载速度
pip install flask
# 观察下载地址是否以 https://pypi.tuna.tsinghua.edu.cn 开头
# 如果下载速度明显变快（几 MB/s），说明配置成功

避坑：如果仍然提示 SSL 证书错误，在配置文件中加 trusted-host 项（如上所示）。正式环境不推荐这样做，有安全隐患，但用于学习和开发环境足够。

八、进阶工具：pipx / poetry / pipenv

8.1 pipx：全局安装 CLI 工具但不污染环境

问题：有些工具是全局使用的（如 black 格式化代码、httpie 测试 API），但如果装在全局环境，会和各种项目环境冲突。

pipx 解决：把 CLI 工具装在独立的隔离环境中，但让它们在全局终端可用。

# 安装 pipx
pip install pipx
pipx ensurepath   # 把 pipx 的路径加到 PATH

# 用 pipx 安装全局 CLI 工具
pipx install black
pipx install httpie

# 之后就可以在任何地方使用
black --version
http --help

# pipx 安装的每个工具都在自己独立的虚拟环境中，互不干扰

8.2 poetry：现代化的 Python 项目全生命周期管理

poetry 整合了虚拟环境管理 + 依赖解析 + 打包发布，是目前 Python 社区最活跃的依赖管理工具之一。

# 安装（Windows PowerShell）
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# 创建新项目
poetry new my-project
cd my-project

# 添加依赖
poetry add flask
poetry add requests

# Poetry 会自动：
# 1. 创建虚拟环境
# 2. 解析依赖关系（比 pip 更智能，能避免冲突）
# 3. 更新 pyproject.toml（类似 requirements.txt 但更强大）
# 4. 生成 poetry.lock（锁定所有依赖的精确版本）

8.3 pipenv：曾经的主流，现在逐渐被 poetry 替代

# 安装
pip install pipenv

# 创建环境并安装依赖
pipenv install flask
pipenv install requests

# 激活环境
pipenv shell

# 退出
exit

# pipenv 生成 Pipfile 和 Pipfile.lock
# 类似 Node.js 的 package.json

8.4 工具对比

工具 适用阶段 学习曲线 适用场景
venv + pip + requirements.txt 入门 低 学习、简单项目
virtualenv + pip + requirements.txt 入门 低 需兼容 Python 2
pipenv 进阶 中 中型项目
poetry 进阶 中 大型项目、需要发布到 PyPI
pipx 辅助 低 安装全局 CLI 工具

建议：入门阶段先用 venv + pip + requirements.txt。熟练后如果项目变复杂，再过渡到 poetry。

九、常见报错排查手册

报错 1：激活虚拟环境失败

# Windows PowerShell 报错：
# "无法加载文件...因为在此系统上禁止运行脚本"

# 解决：以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser


# Linux/Mac 报错：
# "permission denied: ./bin/activate"

# 解决：
chmod +x myenv/bin/activate

报错 2：pip 安装包超时

# 报错信息：
# Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None))
# after connection broken by 'ConnectTimeoutError'

# 解决1：换镜像源
pip install flask -i https://pypi.tuna.tsinghua.edu.cn/simple

# 解决2：增加超时时间
pip install flask --default-timeout=100

# 解决3：永久配置镜像源（见第七章）

报错 3：依赖版本冲突

# 报错信息：
# ERROR: Cannot install packageX==1.0.0 and packageY==2.0.0 because these
# package versions have conflicting dependencies.

# 解决：
# 1. 用 pip check 定位冲突
pip check

# 2. 手动调整版本号
# 3. 考虑使用 poetry（依赖解析更智能）

报错 4：权限不足（Permission denied）

# Linux/Mac 报错：
# PermissionError: [Errno 13] Permission denied: '/usr/lib/python3.x/...'

# 解决：不要用 sudo pip install，而是在虚拟环境中装
# 如果在虚拟环境中还报错，检查是否真的激活了虚拟环境

报错 5：pip 命令找不到

# 报错信息：
# 'pip' 不是内部或外部命令，也不是可运行的程序

# 解决：
# 1. 确认 Python 已正确安装且添加到 PATH
# 2. 用 python -m pip 替代 pip
python -m pip install flask

报错 6：SSL 证书验证失败

# 报错信息：
# SSL: CERTIFICATE_VERIFY_FAILED

# 解决1：配置信任主机（在 pip.ini / pip.conf 中添加）
# trusted-host = pypi.tuna.tsinghua.edu.cn

# 解决2：临时跳过（不推荐）
pip install flask --trusted-host pypi.org --trusted-host files.pythonhosted.org

报错 7：虚拟环境和全局环境搞混

# 症状：明明在虚拟环境里装了包，但项目还是提示找不到

# 排查：
# 第一步：确认是否已激活虚拟环境（看终端前缀）
# 第二步：确认 IDE（如 VS Code）是否选择了正确的 Python 解释器
#   VS Code：Ctrl+Shift+P → "Python: Select Interpreter" → 选择 venv 中的 python

报错 8：pip freeze 包太多

# 问题：pip freeze 列出了很多你没主动装的包

# 原因：pip freeze 列出的是当前环境中的所有包，包括你装的包的依赖

# 如果你只想列出"顶层依赖"（你手动装的）：
pip install pipdeptree
pipdeptree --warn silence

# 可以更清晰地看到包之间的依赖树

报错 9：删除虚拟环境后终端仍然显示前缀

# 症状：deactivate 了，或者删了虚拟环境文件夹，终端还显示 (myenv)

# 解决：关闭终端窗口，重新打开一个新的

报错 10：pip install -r requirements.txt 部分失败

# 有些包装不上，但其他的装好了

# 解决：
# 1. 先装能装上的（用 --ignore-installed 跳过冲突）
# 2. 逐个排查失败的包
# 3. 检查失败包的版本是否真实存在：
#    访问 https://pypi.org/project/包名/#history 查看版本列表

十、最佳实践 15 条

  1. 永远不要在全局 Python 环境做项目开发——创建虚拟环境是第一件事
  2. 每个项目一个虚拟环境——不要多个项目共享同一个虚拟环境
  3. 虚拟环境文件夹命名为 venv 或 .venv——统一命名，方便 .gitignore 忽略
  4. 激活虚拟环境是"每次打开终端"都要做的事——它不会永久绑定
  5. 生成 requirements.txt 用 pip freeze > requirements.txt——不要手动编辑包名
  6. requirements.txt 提交到 Git，venv 文件夹不提交——在 .gitignore 中忽略 venv
  7. 安装新包后立即更新 requirements.txt——pip freeze > requirements.txt
  8. 拉取代码后立即同步依赖——pip install -r requirements.txt
  9. 使用 python -m pip 而不是裸 pip——确保使用正确 Python 对应的 pip
  10. 配置国内镜像源——节省大量等待时间
  11. 不要在虚拟环境里用 sudo pip install（Linux/Mac）——用 sudo 会绕过虚拟环境
  12. 定期升级 pip——python -m pip install --upgrade pip
  13. 当依赖复杂到 requirements.txt 难以维护时，迁移到 poetry
  14. 遇到依赖冲突先用 pip check 定位问题
  15. 在交付项目时附带 requirements.txt 或 pyproject.toml——这是环境复刻的"配方"

十一、课后实操作业

作业 1：虚拟环境基础操作（必做）

  1. 创建一个名为 project_alpha 的虚拟环境（用 venv）
  2. 激活它，安装 flask、requests、pandas 三个包
  3. 生成 requirements.txt
  4. 退出并删除 project_alpha 虚拟环境
  5. 创建一个新的虚拟环境 project_beta，用 requirements.txt 还原所有依赖
  6. 确认还原成功（pip list 对比）

作业 2：版本冲突模拟（必做）

  1. 创建虚拟环境 env_v1，安装 flask==2.0.3
  2. 创建虚拟环境 env_v2，安装 flask==3.0.0
  3. 分别激活两个环境，验证 flask --version 输出不同的版本号
  4. 思考：如果没有虚拟环境，这个问题怎么解决？

作业 3：镜像源配置（必做）

  1. 将 pip 的默认源永久配置为清华镜像源
  2. 运行 pip config list 确认配置生效
  3. 安装一个包，观察下载速度是否明显变快

作业 4：Git 版本控制（选做）

  1. 创建一个 Git 仓库，初始化
  2. 创建虚拟环境 venv，安装 requests
  3. 编写 .gitignore，确认 venv/ 被忽略
  4. git add . 并确认 venv/ 文件夹没有被添加到暂存区

作业 5：工具探索（选做）

  1. 安装 pipx，用 pipx 安装 black 代码格式化工具
  2. 尝试用 black 格式化一段 Python 代码
  3. （进阶）安装 poetry，用 poetry new 创建一个项目，体会和 venv+pip 流程的差异

总结

Python 依赖管理全流程图：

创建项目
   │
   ├─→ python -m venv venv    （创建虚拟环境）
   │
   ├─→ 激活虚拟环境             （每次打开终端都要做）
   │
   ├─→ pip install 需要的包     （在虚拟环境中安装）
   │
   ├─→ pip freeze > requirements.txt   （导出依赖清单）
   │
   ├─→ 在 .gitignore 中忽略 venv/     （不提交虚拟环境）
   │
   ├─→ git add requirements.txt        （提交依赖清单）
   │
   └─→ 其他人 git clone 后：
         python -m venv venv
         激活
         pip install -r requirements.txt  ← 一键还原环境

核心心法三句话：

  1. 虚拟环境 = 项目的独立"工具箱"——每个项目一个，互不干扰
  2. requirements.txt = 工具箱的"清单"——有了它，去哪都能原样还原
  3. 永远不在全局装项目依赖——这是 Python 开发的第一条纪律
0
Python

  1. 微信打赏

    qrcode weixin
版权归属： 忆全栈
本文链接： https://www.jsopy.com/archives/bbRbjwN2
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权
博主关闭了当前页面的评论