uv 现代 Python 环境管理手册
uv 现代 Python 环境管理手册
本文档总结了在 Windows 环境下从 Miniforge 彻底迁移到 uv 的操作流程，旨在为工业数字化及 AI 研究项目提供稳定、高速的开发环境。
一、 彻底清理旧环境 (Miniforge/Conda)
在切换到 uv 之前，确保旧环境已清理干净，避免路径冲突：
- 官方卸载/手动删除：即使控制面板中没有卸载选项，也应优先进入安装目录（如 C:\ProgramData\miniforge3 或 C:\Users\用户名\miniforge3）查找 Uninstall-Miniforge3.exe。运行该程序可自动清理注册表。若无卸载程序，再手动删除整个文件夹。
- 环境变量：在系统环境变量的 Path 中删除所有指向 miniforge 或 conda 的条目。
- 配置文件与用户目录：用户目录通常位于 C:\Users\你的用户名（例如 C:\Users\Zhu Qingchuan）。你需要在此目录下删除 .condarc 文件和 .conda 文件夹。这是彻底清除 VS Code 解释器列表中旧环境残留的关键步骤。
- 执行别名：在 Windows 设置中关闭“应用执行别名”里的 Python 拦截。
二、 uv 的安装与路径配置
- 安装命令 (PowerShell)：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - 路径生效：安装后若无法识别 uv 命令，需将 C:\Users\用户名\.local\bin 手动添加到系统环境变量 Path 中，或重启终端。
- 自更新：定期运行 uv self update 保持工具处于最新版本。
三、 Python 版本管理 (避坑指南)
对于 AI 项目（如 FastAPI, llama-cpp, Pillow），版本稳定性至关重要：
- 安装指定版本：建议安装成熟的 3.12 版本，避免使用尚未普及的 3.14 预览版。
uv python install 3.12 - 项目版本锁定：在项目根目录下强制锁定版本，确保 uv run 调用的是正确的解释器。
uv python pin 3.12 - 配置修改：若报错版本不兼容，需在 pyproject.toml 中将 requires-python 修改为 “>=3.12”。
四、 项目初始化与依赖管理
针对已有 requirements.txt 的项目，采用以下标准流程：
- 初始化：
uv init（生成项目描述文件 pyproject.toml）。 - 创建环境：
uv venv（在当前目录生成 .venv）。 - 导入依赖：
uv add -r requirements.txt。- 注：uv add 会自动解析并写入 pyproject.toml。若只想单纯安装不记录，使用 uv pip install -r requirements.txt。
- 同步环境：
uv sync（确保本地 .venv 与配置文件完全一致）。
uv init
uv venv
uv add -r requirements.txt
uv sync
五、 自动化运行与脚本优化
- 免激活运行：无需 activate 环境，直接使用 uv run <脚本名> 启动，uv 会自动关联虚拟环境。
- 批处理脚本 (.bat)：利用 %~dp0 定位路径，确保双击即可启动 FastAPI 后端。
@echo off uv run uvicorn app_fastapi:app --host 127.0.0.1 --port 17865 pause - 快捷指令：在 pyproject.toml 的
[project.scripts]模块配置别名，实现uv run start这种极简操作。
六、 网络代理与镜像源深度配置
在处理涉及海外资源的 AI 项目时，网络连接是核心环节。以下是针对不同网络策略的具体实现方案：
1. 系统代理配置 (以 Clash 为例)
uv 会自动识别系统的 HTTP_PROXY 环境变量。如果自动识别失败，可在终端中手动指定：
- PowerShell (临时生效):
$env:HTTP_PROXY = "http://127.0.0.1:7890" $env:HTTPS_PROXY = "http://127.0.0.1:7890" - CMD (临时生效):
set HTTP_PROXY=http://127.0.0.1:7890 set HTTPS_PROXY=http://127.0.0.1:7890 - 永久生效: 建议在“系统环境变量”中添加上述两个变量，地址通常为 http://127.0.0.1:7890。
2. 国内主流镜像源地址
若代理不稳定或在无外网环境下工作，推荐使用以下高速镜像源：
- 清华大学 (TUNA): https://pypi.tuna.tsinghua.edu.cn/simple
- 阿里云 (Aliyun): https://mirrors.aliyun.com/pypi/simple/
- 百度 (Baidu): https://mirror.baidu.com/pypi/simple
3. 通过 pyproject.toml 固定镜像源
在项目配置文件中直接写入索引，可确保所有协作者都使用相同的下载源：
[[tool.uv.index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true # 将此源设为默认搜索源
4. 处理 SSL 证书与安全限制
在使用代理下载特定 AI 库时，若遇到 SSL 证书验证报错，可尝试以下紧急方案：
- 跳过证书校验 (不推荐长期使用): 设置环境变量 UV_INSECURE = “true”。
- 检查代理模式: 确保 Clash 未开启“HTTPS 解密”或“MITM”功能，这通常是导致证书报错的元凶。
七、 Git 版本控制最佳实践
为了确保 2027 年结题时环境仍能复现，请严格遵守提交规范：
- 必须提交：pyproject.toml（项目蓝图）和 uv.lock（精确的版本快照）。
- 必须忽略：在 .gitignore 中加入 .venv/、__pycache__/ 以及大型模型权重文件夹（如 models/）。
八、 VS Code 开发环境配置
为了在编辑器中获得完整的语法支持和调试能力，需要进行以下关键设置：
- 插件安装：在左侧扩展商店搜索并安装 Microsoft 官方提供的 “Python” 插件。它是实现环境自动识别、代码补全和调试的基础。
- 选择解释器：在编辑器内按下 Ctrl + Shift + P，输入 Python: Select Interpreter。在弹出的列表中，始终优先选择标记为 “Recommended” 的项，其路径应指向项目目录内的 .venv\Scripts\python.exe。
- 清理过时环境残留：若列表中仍显示已删除的环境（如 smart_design），需前往用户目录 C:\Users\你的用户名 手动删除 .conda 文件夹，随后点击 VS Code 解释器选择框右上角的刷新图标即可。
- 终端自动化：配置完成后，VS Code 的内置终端在启动时会自动运行激活脚本，你会看到类似 (.venv) 或 (项目名) 的前缀，这表示开发环境已准备就绪。