每周 Python 虚拟环境与依赖安装手册
使用时间：每周新建 Python 项目的第一天；换电脑、重建环境或出现“安装成功却导入失败”时也使用。
标准路线：Python 3.12 + 自带venv+python -m pip。
本手册刻意不要求uv，避免学生为了环境管理再安装一层工具。
1. 先分清“软件”和“项目依赖”
| 类型 | 课程示例 | 怎样获得 |
|---|---|---|
| 系统软件 | Python、TRAE、Git、Node.js、Docker Desktop | 使用各自安装手册 |
| Python 标准库 | sqlite3、json、pathlib、unittest | 随 Python 提供，无需另装 |
| Python 项目包 | pytest、FastAPI、Uvicorn、Pydantic、SQLAlchemy、PyMySQL、Streamlit、LangChain Text Splitters、MCP SDK、LangGraph、Pandas、Requests、MySQL Connector | 只在当前项目 .venv 中按依赖清单安装 |
| 云端能力 | GitHub Actions、DeepSeek、火山方舟 | 账号和网络配置，不是本机软件 |
所以，看到 import sqlite3 不要去下载 SQLite；看到 import streamlit 也不要找 Streamlit 桌面安装包。
2. 每周统一的六步流程
假设本周项目目录叫 W04-llm-customer-service。
第一步：确认当前目录
Get-Location
Get-ChildItem必须看到本周项目的 requirements.txt 或正在创建的项目文件。不要在整个课程父目录中创建一个共享 .venv。
第二步：确认 Python 3.12
py -3.12 -V若可用，创建环境：
py -3.12 -m venv .venv若 py 不可用，但下列命令明确显示 3.12.x：
python -V则可使用：
python -m venv .venv第三步：让 TRAE 选中 .venv
在 TRAE 选择当前项目的 .venv 解释器，关闭旧终端并新开终端。课堂不强制执行 Activate.ps1，因为 PowerShell 执行策略可能阻止激活脚本；TRAE 明确选择解释器后，新终端中的 python 应直接指向项目环境。
python -V
python -c "import sys; print(sys.executable); print(sys.prefix)"
python -m pip --version三条路径都应属于本周项目的 .venv。
第四步：升级项目内的 pip
python -m pip install --upgrade pip网络或组织策略不允许升级时，先记录错误；只要当前 pip 能正确安装锁定依赖，不要为了追求“最新版”中断课堂。
第五步：按依赖清单安装
只有 requirements.txt 时：
python -m pip install -r requirements.txt项目同时提供 requirements.txt 和 requirements-dev.txt 时：
python -m pip install -r requirements-dev.txt后者通常已经包含或引用运行依赖，并额外加入测试/格式检查工具。不要在没读文件的情况下两份反复安装。
第六步：检查和最小运行
python -m pip check
python -m pip list
python -m pytest -q再按项目类型做一个最小功能验收：
# W03 FastAPI
python -m uvicorn app.main:app --reload
# W05 Streamlit
python -m streamlit run student_starter/app.py安装命令退出码为 0 只证明安装进程结束；能导入、能运行、测试通过才证明项目环境可用。
3. 每周依赖对应表
| 周次 | 主要依赖 | 单独安装桌面软件？ | 最小验收 |
|---|---|---|---|
| W01 | Python 标准库为主 | 否 | src/order_rules.py 运行、测试与 Git 快照通过 |
| W02 | pytest >=8,<9 | 否 | python -m pytest --version 与项目测试通过 |
| W03 | FastAPI 0.141.1、Uvicorn 0.41.0、Pydantic 2.13.4、pytest 9.1.1；D02 加 SQLAlchemy 2.0.48、PyMySQL 1.1.2 | MySQL 需另装 | /docs、API 测试、真实 MySQL 事务分别验收 |
| W04 | Pydantic >=2.10,<3 与项目 Provider Adapter 依赖 | 否 | Replay 测试先通过；真实 API 另走本人 Key 与成本门 |
| W05 | Streamlit 1.62.0、pytest 9.1.1 | 否 | 8501 页面、AppTest、真实浏览器分别验收 |
| W06 | FastAPI 0.141.1、LangChain Text Splitters 1.1.2、pytest 9.1.1 | 否 | 离线检索测试先通过；Embedding/Generation 真实证据另验 |
| W07 | MCP Python SDK 2.1.1 | 否 | 独立 stdio Client/Server、工具集合与退出状态通过 |
| W08 | LangGraph 1.2.11、Checkpoint SQLite 3.1.1 | 否 | 工作流评测、Checkpoint 与新进程恢复分别通过 |
| W09 | openpyxl >=3.1,<4（教师 Fixture 处理） | 影刀需另装 | Fixture/Lab 与影刀真实流程分层验收 |
| W10 | pandas >=2.2,<3.1、requests >=2.32,<3、mysql-connector-python >=9,<10、openpyxl >=3.1,<4、pytest >=8,<9 | 复用 MySQL | import smoke、数据质量测试、API/MySQL 对账通过 |
版本以每个项目的 requirements*.txt 为准，不在系统环境全局追求同一套“最新版”。
4. Streamlit 首次启动（W05-D03）
在包含 streamlit_app.py 的项目根目录执行：
python -m streamlit run streamlit_app.py终端应显示本地地址，通常为 http://localhost:8501。在浏览器真实操作页面，并按 Ctrl + C 停止服务。
常见问题：
| 现象 | 检查 |
|---|---|
No module named streamlit | python -m pip --version 是否属于当前 .venv；是否安装了正确依赖文件 |
| 8501 被占用 | 找到旧 Streamlit 终端并 Ctrl + C；必要时临时使用 --server.port 8502 |
| 页面打开但数据不对 | 这不是安装问题；检查工作目录、配置、数据文件和浏览器 Network |
| 命令一关终端页面就失效 | Streamlit 是本地进程，终端必须保持运行 |
5. 常见依赖故障
安装成功但仍然 ModuleNotFoundError
python -c "import sys; print(sys.executable)"
python -m pip --version两条路径不在同一 .venv 时，重新让 TRAE 选择项目解释器并新开终端。不要继续重复安装。
PowerShell 禁止运行 Activate.ps1
课程标准路径不要求修改全局执行策略。用 TRAE 选择 .venv，或直接使用环境中的解释器路径完成一次诊断：
.\.venv\Scripts\python.exe -V
.\.venv\Scripts\python.exe -m pip --version下载慢、证书或代理错误
- 保存第一条真实错误和完整包名。
- 先确认浏览器能访问 PyPI；组织网络使用组织批准的代理或镜像。
- 教师离线包必须提前在同版本 Python/Windows 上验证并记录来源、版本和哈希。
- 不使用来历不明的
pip.ini，不关闭 TLS 校验。
ResolutionImpossible 或版本冲突
检查是不是在旧环境上叠加了另一周依赖。每周独立 .venv，必要时在确认没有需保留内容后重建；不要随意删除依赖版本号来“让它装上”。
C/C++ 编译工具报错
先核对 Python 是否为课程支持的 3.12 64 位，以及依赖是否提供匹配的预编译 wheel。不要一看到编译报错就立刻安装完整 Visual Studio；先确认不是误用 Python 3.14 或错误架构。
6. 关于 uv
教师参考工程可以使用 uv 加速备课，但学生标准手册不依赖它。若某页仍出现：
uv venv --python 3.12 .venv
uv pip install --python .venv -r requirements.txt学生可以等价改用：
py -3.12 -m venv .venv
# 在 TRAE 选择 .venv 并新开终端
python -m pip install -r requirements.txt这不是降级；两条路线的共同验收都是项目解释器路径、锁定依赖和真实运行。
7. 每周环境记录模板
项目目录：
Python 版本：
sys.executable：
pip 路径：
安装使用的依赖文件：
python -m pip check：通过 / 失败
最小运行命令：
最小运行结果：
测试结果：
网络/平台限制：