解释器、虚拟环境与依赖
本节目标
学完本节，你应能在 Windows 11 + PowerShell 7 中确认正在使用哪个 Python，解释解释器、venv、pip、依赖声明与锁定的职责，并从 venv + pip 过渡到按需使用 uv。
先分清五个对象
| 对象 | 回答的问题 | 常见检查 |
|---|---|---|
| Python 解释器 | 哪个程序在执行 .py？ | python --version、Get-Command python |
| 虚拟环境 | 这个项目使用哪套隔离的解释器与包？ | python -c "import sys; print(sys.executable)" |
包管理器 pip | 把哪个分发包装进当前环境？ | python -m pip --version |
| 依赖声明 | 项目允许或需要哪些包/版本？ | pyproject.toml 或 requirements 文件 |
| 锁定结果 | 本次可复现安装解析到了哪些精确版本？ | 锁文件及其工具说明 |
激活虚拟环境的主要作用是在当前 shell 的 PATH 前面放入环境目录；激活脚本还会设置 VIRTUAL_ENV，并可能调整提示符。它不会修改源代码，也不会保证依赖已经按项目声明同步。
版本基线
截至 2026-07-14，Python.org 下载页列出的最新稳定版是 Python 3.14.6；Python 3.15 仍是预发布分支。课程示例避免依赖 3.14 独有语法，以便在仍受支持的 3.11+ 环境运行。真实项目应在 pyproject.toml 或运行文档中写明支持范围，并在 CI/测试中验证，而不是默认“Python 3 都一样”。
原 Python 100 Days 教程跨越多个生态时期。遇到旧安装截图、旧包名或旧 API 时，保留其教学语境，但以项目锁定版本和当前官方文档为准。
用 venv + pip 建立最小环境
在 vault 之外的新练习目录执行：
New-Item -ItemType Directory -Path "$HOME\python-agent-lab" -Force
Set-Location "$HOME\python-agent-lab"
python --version
Get-Command python
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip install --upgrade pip若执行策略阻止激活，可先直接调用环境解释器，而不是立刻放宽整机策略：
.\.venv\Scripts\python.exe -m pip --version
.\.venv\Scripts\python.exe .\main.py.venv 是可重建的本机状态，不应加入 Git 或本 vault。删除环境不会删除项目源代码，但重新安装前要保留依赖声明与锁定信息。
为什么使用 python -m pip
机器可能同时有多个 Python 和 pip.exe。python -m pip 明确表示“让当前这个解释器执行其 pip 模块”，比单独输入 pip 更容易确认目标环境。
检查三件事：
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip check路径应指向同一 .venv；pip check 检查已安装包声明的依赖是否兼容，但不能证明应用行为正确或供应链安全。
依赖声明与锁定不是同一件事
pyproject.toml 可以声明项目元数据、Python 版本和直接依赖；requirements 文件常用于记录或约束安装集合。锁文件通常由具体工具产生，记录解析后的精确版本与完整依赖图。
最小概念示例：
[project]
name = "agent-lab"
version = "0.1.0"
requires-python = ">=3.11,<3.15"
dependencies = []本库示例只使用标准库，所以不需要安装第三方依赖。若项目引入 SDK，应记录：为什么需要、允许的版本范围、更新方式、许可证与安全审查、回归测试和回滚目标。
不要把真实令牌写进依赖文件、命令历史或安装 URL。额外软件源可能产生依赖混淆风险，必须由组织明确配置与审核。
什么时候再使用 uv
uv 是 Astral 提供的第三方 Python 项目与包管理工具，可管理 Python、虚拟环境、依赖、锁文件和工具执行。先理解前述对象，再考虑：
uv init agent-lab
Set-Location .\agent-lab
uv run python --version
uv add httpx
uv lock
uv sync命令会随 uv 版本发展，实施时查官方文档并锁定团队用法。uv 管理的 Python 发行物来源也不同于 python.org 官方安装器；有合规或运行时来源要求时必须核对。不要把 uv 当成“无需理解环境”的魔法层。
常见错误与排查
| 现象 | 先检查 | 常见根因 |
|---|---|---|
安装成功却 import 失败 | sys.executable 与 pip --version | 包装进了另一个解释器 |
| 关闭终端后环境失效 | 是否重新激活 | 激活只影响当前 shell |
| 同事无法复现 | 依赖声明、锁文件、Python 范围 | 只分享了 .venv 或口头版本 |
| 升级后行为变化 | 解析版本与变更记录 | 使用无上限依赖且没跑回归 |
| Git 出现大量环境文件 | .gitignore 与状态 | 错把 .venv 放进版本控制 |
练习
在 vault 外创建环境，记录 python --version、sys.executable 与 python -m pip --version。退出并重新打开 PowerShell，再分别用“激活”和“直接调用 .venv\Scripts\python.exe”运行同一脚本，解释两者差别。
自测
- 解释器、虚拟环境和
pip分别负责什么？ - 为什么
.venv不应提交，而依赖声明应提交？ - 版本范围与锁文件解决的是同一个问题吗？
python -m pip为什么比裸pip更容易排错？- 使用
uv前仍需理解哪些基础对象？
相关概念与下一步
参考资料
获取日期：2026-07-14。