Python 环境彻底不乱：uv、pip、venv、Conda 怎么选？Windows 项目迁移与锁版本实战

Python 环境彻底不乱：uv、pip、venv、Conda 怎么选？Windows 项目迁移与锁版本实战

"明明安装了 requests，运行时却提示 ModuleNotFoundError""我的电脑能跑，同事和 CI 一装就报依赖冲突""项目换了目录，原来的 .venv 突然失效"------Python 环境问题往往不是包没有安装，而是包被装进了另一个解释器、依赖没有被可靠锁定，或者把不可移动的虚拟环境当成了项目文件。

过去我们常用 pip + venv + requirements.txt 解决这些问题。它们仍然可靠、标准、值得掌握，但项目还需要自己补齐 Python 版本选择、依赖解析、锁文件、运行入口和 CI 同步。uv 把这些环节合并进一套工作流；Conda 则擅长管理 Python 之外的原生库、编译工具链和科学计算环境。三者没有绝对胜负，关键是先分清"包安装器、虚拟环境、项目管理器、通用二进制环境管理器"分别解决什么。

本文以 Windows 旧项目迁移为主线：先建立选择模型，再把 requirements.txt 平滑迁移到 pyproject.toml + uv.lock，解释开发机与 CI 如何复现，最后系统排查 pip/python 路径错位、PowerShell 激活失败、移动 .venv、锁文件过期和 Conda 混装等常见问题。

一、先给结论：多数通用项目可以优先试 uv

教学图：三个工具组合在 Python 管理、依赖声明、锁版本和原生二进制依赖上的边界。由 Image2 生成。

如果你开发 FastAPI、Django、爬虫、自动化脚本、数据处理服务或普通 AI 应用，且主要依赖来自 PyPI，可以优先尝试 uv 项目模式；它能管理 Python 版本、项目虚拟环境、依赖声明、通用锁文件和命令运行。若课程要求只用标准库工具、项目很小或需要理解底层机制，python -m venv 加 python -m pip 足够。若环境依赖 CUDA、MKL、GDAL、Fortran、系统级动态库或复杂科学软件栈，Conda 仍有价值，因为它不局限于 Python 包。

不要把 pip 与 venv 当成同一工具。pip 负责安装 Python 分发包，venv 基于已有 Python 创建隔离环境；它们默认不替你挑选 Python，也不天然生成完整跨平台锁文件。uv 的项目模式更像一个统一入口，而 uv pip 是面向既有 pip 工作流的兼容接口，两者的使用目标不同。
#mermaid-svg-YBqBKwqM7uO2565c{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-YBqBKwqM7uO2565c .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-YBqBKwqM7uO2565c .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-YBqBKwqM7uO2565c .error-icon{fill:#552222;}#mermaid-svg-YBqBKwqM7uO2565c .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-YBqBKwqM7uO2565c .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-YBqBKwqM7uO2565c .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-YBqBKwqM7uO2565c .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-YBqBKwqM7uO2565c .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-YBqBKwqM7uO2565c .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-YBqBKwqM7uO2565c .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-YBqBKwqM7uO2565c .marker{fill:#333333;stroke:#333333;}#mermaid-svg-YBqBKwqM7uO2565c .marker.cross{stroke:#333333;}#mermaid-svg-YBqBKwqM7uO2565c svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-YBqBKwqM7uO2565c p{margin:0;}#mermaid-svg-YBqBKwqM7uO2565c .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-YBqBKwqM7uO2565c .cluster-label text{fill:#333;}#mermaid-svg-YBqBKwqM7uO2565c .cluster-label span{color:#333;}#mermaid-svg-YBqBKwqM7uO2565c .cluster-label span p{background-color:transparent;}#mermaid-svg-YBqBKwqM7uO2565c .label text,#mermaid-svg-YBqBKwqM7uO2565c span{fill:#333;color:#333;}#mermaid-svg-YBqBKwqM7uO2565c .node rect,#mermaid-svg-YBqBKwqM7uO2565c .node circle,#mermaid-svg-YBqBKwqM7uO2565c .node ellipse,#mermaid-svg-YBqBKwqM7uO2565c .node polygon,#mermaid-svg-YBqBKwqM7uO2565c .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-YBqBKwqM7uO2565c .rough-node .label text,#mermaid-svg-YBqBKwqM7uO2565c .node .label text,#mermaid-svg-YBqBKwqM7uO2565c .image-shape .label,#mermaid-svg-YBqBKwqM7uO2565c .icon-shape .label{text-anchor:middle;}#mermaid-svg-YBqBKwqM7uO2565c .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-YBqBKwqM7uO2565c .rough-node .label,#mermaid-svg-YBqBKwqM7uO2565c .node .label,#mermaid-svg-YBqBKwqM7uO2565c .image-shape .label,#mermaid-svg-YBqBKwqM7uO2565c .icon-shape .label{text-align:center;}#mermaid-svg-YBqBKwqM7uO2565c .node.clickable{cursor:pointer;}#mermaid-svg-YBqBKwqM7uO2565c .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-YBqBKwqM7uO2565c .arrowheadPath{fill:#333333;}#mermaid-svg-YBqBKwqM7uO2565c .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-YBqBKwqM7uO2565c .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-YBqBKwqM7uO2565c .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YBqBKwqM7uO2565c .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-YBqBKwqM7uO2565c .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YBqBKwqM7uO2565c .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-YBqBKwqM7uO2565c .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-YBqBKwqM7uO2565c .cluster text{fill:#333;}#mermaid-svg-YBqBKwqM7uO2565c .cluster span{color:#333;}#mermaid-svg-YBqBKwqM7uO2565c div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-YBqBKwqM7uO2565c .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-YBqBKwqM7uO2565c rect.text{fill:none;stroke-width:0;}#mermaid-svg-YBqBKwqM7uO2565c .icon-shape,#mermaid-svg-YBqBKwqM7uO2565c .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YBqBKwqM7uO2565c .icon-shape p,#mermaid-svg-YBqBKwqM7uO2565c .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-YBqBKwqM7uO2565c .icon-shape .label rect,#mermaid-svg-YBqBKwqM7uO2565c .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YBqBKwqM7uO2565c .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-YBqBKwqM7uO2565c .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-YBqBKwqM7uO2565c :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
是
否
新 Python 项目
需要管理 CUDA、MKL 等非 Python 依赖？
优先评估 Conda
只做教学脚本或最小标准环境？
pip + venv
uv 项目模式
pyproject.toml + uv.lock + .python-version
environment.yml + 明确 channel
requirements.txt + 独立锁定流程

二、Python 环境为什么总会"装了却找不到"

Windows 上可能同时存在 Microsoft Store Python、python.org 安装版、Conda、IDE 自带解释器和 uv 管理的 Python。终端运行 pip install 时，pip.exe 可能绑定 Python A；IDE 运行代码时却使用 Python B。安装成功与 import 失败于是同时成立。

排错时不要先重装包，先确认解释器身份：

where.exe python
where.exe pip
python -c "import sys; print(sys.executable)"
python -m pip --version

最后两条路径应该属于同一个解释器或同一虚拟环境。传统 pip 工作流中优先使用 python -m pip install 包名，因为它明确让"当前这个 python"运行 pip 模块，比直接调用 PATH 中第一个 pip.exe 更可靠。uv 项目中则可使用 uv run python，它会在项目环境中执行，不要求先激活。

项目附带的 code/environment_probe.py 会输出 sys.executable、sys.prefix、sys.base_prefix、site-packages 和 VIRTUAL_ENV。判断是否真正运行在虚拟环境中，应看 sys.prefix != sys.base_prefix；不能只依赖 VIRTUAL_ENV，因为虚拟环境不激活也能通过完整解释器路径执行。

三、venv 的本质：隔离目录，不是可复制容器

官方证据图。来源：Python Documentation，《venv --- Creation of virtual environments》，原始链接：https://docs.python.org/3/library/venv.html

Python 官方文档说明，venv 基于一个已有的基础解释器创建独立环境，Windows 下包含 Scripts 和 Lib\site-packages。激活脚本只是把虚拟环境目录放到 PATH 前面；激活不是使用 venv 的必要条件。下面两种执行方式都可以：

.\.venv\Scripts\Activate.ps1
python app.py

# 不激活，直接指定解释器
.\.venv\Scripts\python.exe app.py

虚拟环境通常不可移动。安装的脚本会记录解释器绝对路径，pyvenv.cfg 也关联基础 Python。复制 .venv 到另一台机器、提交 Git、改项目父目录或把 Windows 环境带到 Linux，都会留下脆弱路径。正确策略是提交"环境配方"，在目标机器重新创建环境。Git 应保存 pyproject.toml、锁文件和 Python 版本声明，不保存 .venv。

PowerShell 提示无法加载 Activate.ps1 时，先运行 Get-ExecutionPolicy -List 判断作用域，而不是盲目关闭安全策略。若组织策略不允许修改，可直接使用 .venv\Scripts\python.exe 或 uv run；激活只是便利功能，不应成为项目能否运行的前提。

四、uv 项目的四个关键文件

封面中的现代项目结构不是为了"多几个配置文件"，而是把不同层次拆清楚：

• pyproject.toml：声明项目元数据、Python 范围和直接依赖，适合人工维护。
• uv.lock：记录精确解析结果，由 uv 管理，应提交版本控制，不应手工编辑。
• .python-version：告诉工具项目默认使用哪个 Python 版本。
• .venv：本机生成的隔离环境，不提交、不跨机器复制。

Astral 官方文档说明，uv run 会在执行前检查锁文件与 pyproject.toml 是否一致，并确保项目环境同步；uv sync 默认执行精确同步，会删除锁文件之外的多余包。这能减少开发机"偷偷装过一个包所以能跑"的隐性状态，但也意味着不要把临时调试包随手装进项目环境后期待永久保留，应通过 uv add 或依赖组明确声明。

官方证据图。来源：Astral uv Docs，《Locking and syncing》，原始链接：https://docs.astral.sh/uv/concepts/projects/sync/

常用命令链：

uv init my-project
cd my-project
uv python pin 3.12
uv add httpx
uv add --dev pytest
uv sync
uv run pytest

锁文件不是"永远自动升级"。已有 uv.lock 时，uv 优先保留已锁版本；要升级全部依赖使用 uv lock --upgrade，只升级单包使用 uv lock --upgrade-package 包名。CI 应使用 uv lock --check 或 uv sync --locked，发现声明与锁文件不一致就失败，而不是在构建机悄悄改锁。

五、旧 requirements.txt 平滑迁移，不要一次推翻

教学图：从审计、建分支、导入、锁定到 CI 切换和清理旧环境的完整迁移路径。由 Image2 生成。

第一步先记录现状：当前 Python 完整版本、直接依赖、平台条件、私有源、Git 依赖和测试命令。pip freeze 包含大量传递依赖，不能自动说明哪些是业务直接使用的包；如果项目有 requirements.in，它通常比 freeze 结果更适合作为直接依赖来源。

第二步创建迁移分支，并保留旧环境作为回滚点。然后初始化项目：

git switch -c migrate-to-uv
uv init

若已有未钉死的 requirements.in 和当前精确版本 requirements.txt，官方迁移文档推荐把前者作为依赖声明、后者作为约束，从而首次生成锁文件时尽量保留现有版本：

uv add -r requirements.in -c requirements.txt
uv lock --check
uv sync --locked

如果只有 requirements.txt，先区分它是"人工直接依赖列表"还是 pip freeze 产物。前者可以直接导入；后者应先通过代码导入、文档和测试识别直接依赖，避免把历史遗留包永久固化。迁移目标不是换一个安装命令，而是得到能解释、能升级、能回滚的依赖图。

第三步让编辑器选择项目 .venv，运行单元测试、集成测试、命令行脚本和打包流程。第四步更新 CI，在干净机器安装 uv，然后执行 uv sync --locked 与 uv run pytest。本地和 CI 全部通过后再删除旧环境；不要先删唯一可用环境再开始排错。

六、完整可运行的环境诊断示例

素材包 code/ 中提供：

• pyproject.toml：声明 Python 3.11+、httpx 与 pytest 开发组。
• environment_probe.py：只用标准库输出实际解释器和环境路径。
• diagnose-python.ps1：检查 PATH 中的 python、pip 和项目 .venv。

即使机器还没有 uv，也能先运行探针：

python code/environment_probe.py

在 uv 已安装的环境中可以完整复现：

cd code
uv sync
uv run python environment_probe.py
uv run python -c "import httpx; print(httpx.__version__)"

本文已使用 Python 3.12 对 environment_probe.py 做语法编译与运行检查。由于当前执行环境没有安装 uv，没有伪造 uv 性能数据，也没有声称完成联网依赖安装；配置文件与命令依据官方文档做结构核验。真正发布性能对比时必须记录 uv、pip、Python 版本、网络、缓存冷热状态和重复次数，否则"快几十倍"没有可复现意义。

七、从开发机到 CI，怎样保证可复现

教学图：依赖声明、锁文件、Python 版本、缓存、本地环境和 CI 的边界。由 Image2 生成。
#mermaid-svg-FnahVN9i2sGMJFmP{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FnahVN9i2sGMJFmP .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FnahVN9i2sGMJFmP .error-icon{fill:#552222;}#mermaid-svg-FnahVN9i2sGMJFmP .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FnahVN9i2sGMJFmP .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FnahVN9i2sGMJFmP .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FnahVN9i2sGMJFmP .marker.cross{stroke:#333333;}#mermaid-svg-FnahVN9i2sGMJFmP svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FnahVN9i2sGMJFmP p{margin:0;}#mermaid-svg-FnahVN9i2sGMJFmP .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-FnahVN9i2sGMJFmP .cluster-label text{fill:#333;}#mermaid-svg-FnahVN9i2sGMJFmP .cluster-label span{color:#333;}#mermaid-svg-FnahVN9i2sGMJFmP .cluster-label span p{background-color:transparent;}#mermaid-svg-FnahVN9i2sGMJFmP .label text,#mermaid-svg-FnahVN9i2sGMJFmP span{fill:#333;color:#333;}#mermaid-svg-FnahVN9i2sGMJFmP .node rect,#mermaid-svg-FnahVN9i2sGMJFmP .node circle,#mermaid-svg-FnahVN9i2sGMJFmP .node ellipse,#mermaid-svg-FnahVN9i2sGMJFmP .node polygon,#mermaid-svg-FnahVN9i2sGMJFmP .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-FnahVN9i2sGMJFmP .rough-node .label text,#mermaid-svg-FnahVN9i2sGMJFmP .node .label text,#mermaid-svg-FnahVN9i2sGMJFmP .image-shape .label,#mermaid-svg-FnahVN9i2sGMJFmP .icon-shape .label{text-anchor:middle;}#mermaid-svg-FnahVN9i2sGMJFmP .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-FnahVN9i2sGMJFmP .rough-node .label,#mermaid-svg-FnahVN9i2sGMJFmP .node .label,#mermaid-svg-FnahVN9i2sGMJFmP .image-shape .label,#mermaid-svg-FnahVN9i2sGMJFmP .icon-shape .label{text-align:center;}#mermaid-svg-FnahVN9i2sGMJFmP .node.clickable{cursor:pointer;}#mermaid-svg-FnahVN9i2sGMJFmP .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-FnahVN9i2sGMJFmP .arrowheadPath{fill:#333333;}#mermaid-svg-FnahVN9i2sGMJFmP .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-FnahVN9i2sGMJFmP .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-FnahVN9i2sGMJFmP .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FnahVN9i2sGMJFmP .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-FnahVN9i2sGMJFmP .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FnahVN9i2sGMJFmP .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-FnahVN9i2sGMJFmP .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-FnahVN9i2sGMJFmP .cluster text{fill:#333;}#mermaid-svg-FnahVN9i2sGMJFmP .cluster span{color:#333;}#mermaid-svg-FnahVN9i2sGMJFmP div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-FnahVN9i2sGMJFmP .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-FnahVN9i2sGMJFmP rect.text{fill:none;stroke-width:0;}#mermaid-svg-FnahVN9i2sGMJFmP .icon-shape,#mermaid-svg-FnahVN9i2sGMJFmP .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FnahVN9i2sGMJFmP .icon-shape p,#mermaid-svg-FnahVN9i2sGMJFmP .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-FnahVN9i2sGMJFmP .icon-shape .label rect,#mermaid-svg-FnahVN9i2sGMJFmP .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FnahVN9i2sGMJFmP .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-FnahVN9i2sGMJFmP .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-FnahVN9i2sGMJFmP :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 声明直接依赖
解析并生成 uv.lock
提交 pyproject.toml、uv.lock、.python-version
开发机 uv sync
CI: uv sync --locked
uv run pytest
下载缓存
不提交 .venv

缓存与环境不是一回事。uv 缓存保存下载或构建产物，可加速再次安装；.venv 是与解释器、操作系统和路径相关的安装结果。CI 可以缓存 uv 下载缓存，但不应无条件在 Windows、Linux、不同 Python 版本之间复用 .venv。缓存键至少应包含操作系统、架构、Python 版本和锁文件哈希。

对于发布流程，推荐明确区分三个动作：开发时 uv sync 允许根据声明更新锁；评审时提交并检查 uv.lock 的变化；CI 与部署使用 --locked 禁止隐式修改。升级依赖要单独发起，运行测试和安全扫描，不要把日常构建变成随机升级实验。

八、Windows 五类高频冲突排错

教学图：安装后 import 失败、路径错位、激活失败、移动 venv 和 CI 锁不一致的诊断命令。由 Image2 生成。

8.1 安装成功但 import 失败

先比较 python -m pip --version 与 sys.executable，再用当前解释器运行 python -c "import 包名; print(包名.__file__)"。常见原因是包安装进全局 Python，IDE 却使用 .venv，或反过来。

8.2 pip 和 python 指向不同目录

不要继续反复安装。使用 where.exe 找出 PATH 顺序，暂时改用 python -m pip；长期应配置编辑器解释器和终端启动脚本，移除无用 Python 的 PATH 条目。

8.3 PowerShell 无法激活

检查脚本是否存在和执行策略。没有权限改变策略时直接使用 uv run 或 .venv\Scripts\python.exe，不要为了激活项目而把系统策略设成不安全的全局无限制。

8.4 移动项目后环境失效

删除并重建 .venv，不要逐个修改内部绝对路径。环境应由锁文件恢复，而不是当作可搬运资产修补。

8.5 CI 报锁文件过期

本地执行 uv lock --check。如果 pyproject.toml 已改但锁文件未提交，重新 uv lock、审查差异并提交；不要在 CI 去掉 --locked 掩盖流程错误。

九、至少六个容易踩的坑

1. 全局 pip 安装所有项目。 项目 A 升级包会破坏项目 B；每个项目应有独立环境。
2. 提交 .venv。 体积大、路径绑定、跨平台不可用；提交配方与锁文件。
3. 把 pip freeze 当直接依赖设计。 它混入传递依赖与历史包，升级困难；区分声明和锁定。
4. 混用 Conda 与 pip 却不记录顺序。 原生库与 Python 包可能由不同求解器修改；能用 Conda 的先装，必须 pip 的集中到最后并记录验证。
5. 锁文件存在但 CI 不检查。 构建机自动改锁会让一次构建与下一次不同；使用 --locked。
6. 只锁包版本，不锁 Python 范围。 同一依赖在 Python 3.9 与 3.13 上解析结果可能不同；声明 requires-python 与 .python-version。
7. 把缓存命中当环境正确。 缓存可能加速错误安装；失败时检查锁、解释器和平台标签，必要时对具体包清缓存或重装。
8. 为了追新一次升级全部依赖。 应小步升级单包、审查锁文件、跑测试，并保留回滚提交。

十、性能、安全与兼容性建议

安装速度受网络、索引、wheel 是否存在、缓存冷热和依赖图影响。团队应更关注冷启动 CI 时间、缓存命中率、锁解析时间和失败率，而不是只看一次本机秒表。私有源凭据不要写入 pyproject.toml 或提交的配置文件，使用 CI Secret、凭据助手或环境变量，并防止日志打印带 Token 的索引 URL。

10.1 用一次真实迁移演练验证工具，而不是只比较命令

假设一个 AI 接口项目现有 Python 3.11、FastAPI、Pydantic、HTTPX、pytest 和一个仅 Windows 开发机使用的调试包。原来的 requirements.txt 来自 pip freeze，里面有四十多个包。迁移时不要把四十多个包全部复制进 project.dependencies。先通过代码导入、启动命令和测试配置识别直接依赖，再把 pytest 放入开发依赖组，把仅 Windows 需要的包添加平台标记。此时 pyproject.toml 表达的是项目意图，uv.lock 才负责记录完整传递依赖。

建立两台干净验证环境：Windows 开发路径和与生产相同的 Linux CI。两边都从 Git 克隆，不复制旧 .venv，执行锁定同步与测试。需要记录的不是"安装用了几秒"一个数字，而是 Python 版本是否一致、解析结果是否一致、应用启动是否通过、测试数量是否相同、是否出现从源码编译、缓存目录增长多少，以及回滚到旧分支是否仍可运行。

如果 Windows 成功、Linux 失败，先看锁文件中的环境标记和目标包有没有 Linux wheel；不要立即删除锁文件重来。如果两边解析成功但运行行为不同，检查本地是否读取了未提交配置、时区、编码或系统动态库。环境管理工具可以固定 Python 与包，却不能自动固定数据库、操作系统服务和外部命令。需要完整运行时一致性时，应在 uv 管理 Python 依赖之外，再使用容器或部署镜像声明系统层。

性能试验至少分冷缓存和热缓存各五次，清楚记录网络源与代理。冷缓存衡量新机器和首次 CI，热缓存衡量日常迭代；比较 pip 时要使用同一 Python、同一索引、同一依赖集合，并确保双方都从干净环境开始。如果某个包没有 wheel、临时触发本地编译，单次结果会严重偏斜。文章与团队报告都应发布中位数和 P95，而不是只挑最快的一次。

迁移验收还要包含"删掉 .venv 后能否完整恢复"。这是最有价值的一步：关闭编辑器，删除测试环境，在全新目录重新克隆，再按 README 执行唯一推荐命令。如果必须回忆某个手工安装步骤才能成功，就说明依赖声明仍不完整。只有干净重建通过，才可以清理旧 requirements 和旧环境；在此之前它们是回滚资产，而不是垃圾文件。

10.2 磁盘空间也要分层清理

项目 .venv、uv 下载缓存和 uv 管理的 Python 是三类不同数据。某个项目不再使用时，可以重建性地删除该项目 .venv；缓存用于跨项目复用下载产物，频繁全量清空会让下一次安装重新下载。官方提供 uv cache clean 包名 定向清理，也可在确认空间压力后清理全部缓存。清理前先用工具查看缓存目录与大小，不要把工作区、锁文件和缓存混在一个递归删除命令里。

同理，Conda 的环境、包缓存和项目代码也不应一起删。空间治理应先删除确认不用且可由配方重建的环境，再处理缓存，最后才考虑历史项目；任何自动清理都应先解析绝对路径、验证目标仍位于允许根目录，并保留 pyproject.toml、uv.lock 或 environment.yml。这样释放空间不会同时丢掉复现能力。

依赖锁定提升可复现性，不等于自动安全。锁文件会忠实保留旧版本，需要配合依赖漏洞扫描与计划升级。安装 Git 依赖时锁定提交 SHA，谨慎使用不受控分支。企业代理或自签证书环境应通过受管理证书链配置，不要长期关闭 TLS 验证。

跨平台项目要保留环境标记，不要把某个平台的 freeze 文件生硬套给所有机器。包含 CUDA 或系统动态库时，先验证 uv/PyPI wheel 是否满足目标；若不满足，使用 Conda、容器或系统包管理器建立明确边界，而不是强行让一个工具承担所有层次。

十一、上线与迁移检查清单

• where.exe python/pip 与 sys.executable 已确认。
• 每个项目使用独立环境，没有依赖全局 site-packages。
• pyproject.toml 只声明可解释的直接依赖与 Python 范围。
• uv.lock 已提交且未手工编辑。
• .python-version 符合团队和部署平台版本。
• .venv、缓存、密钥均未提交 Git。
• 旧 requirements 迁移时使用约束保留原版本，并有回滚分支。
• 编辑器明确选择项目 .venv。
• CI 使用 uv sync --locked，不会隐式修改锁文件。
• 已测试 Windows、部署系统及目标 Python 版本。
• Conda/pip 混用有固定顺序和环境导出记录。
• 升级依赖采用单独变更并完成测试与安全扫描。

Python 环境稳定的关键不是记住更多安装命令，而是把"解释器、直接依赖、精确解析结果、本机环境、下载缓存"分成五个不同对象。uv 让这条链路更集中，pip 与 venv 提供标准基础，Conda 处理更宽的二进制环境。选择工具以后，再用锁文件、干净重建和 CI 校验形成闭环，才能真正结束"在我电脑上明明可以"的循环。