Python 开发新纪元：uv + VS Code 全流程指南

1. 为什么选择 uv？

uv 是由 Astral 团队（Ruff 的开发者）开发的 Python 超级工具。它采用 Rust 编写，旨在替代 pip、pip-tools、venv、pyenv 和 poetry。其核心优势包括：

• 极致速度：安装包的速度比 pip 快 10-100 倍。
• 磁盘节省：通过底层“硬链接”技术，同一份包在全硬盘只存一次。
• 一站式管理：一个工具搞定 Python 版本、虚拟环境和依赖包。

2. 安装与初始配置

2.1 安装 uv

在终端执行以下命令：

• Windows (PowerShell):

  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• macOS/Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

2.2 优化 Windows 磁盘性能（跨分区配置）

如果你在 D 盘开发，而系统盘在 C 盘，必须修改缓存位置以启用硬链接（零拷贝安装）：

1. 在 D 盘创建文件夹：D:\.uv_cache。
2. 设置环境变量（参考在windows中设置环境变量的通用做法）：
   • UV_CACHE_DIR = D:\.uv_cache
   • UV_LINK_MODE = hardlink
3. 通过命令uv cache dir来检查uv是否设置好了缓存文件位置

3. 在 VS Code 中配置开发环境

3.1 推荐插件清单

1. Python (Microsoft): 基础支持。
2. Pylance: 核心智能提示。
3. Ruff (Astral): 极速的代码检查和格式化工具（建议开启 Editor: Format On Save）。

3.2 配置默认解释器

为了让 VS Code 自动识别 uv 的环境码，按 Ctrl + , 打开设置，搜索并配置：

• Python: Default Interpreter Path: 设置为 ${workspaceFolder}/.venv/Scripts/python.exe (Windows) 或 ${workspaceFolder}/.venv/bin/python (Mac/Linux)。

4. 项目维护工作流

4.1 初始化新项目

uv init  # 创建 pyproject.toml 声明文件
uv venv  # 创建虚拟环境

4.2 管理依赖（最优雅的方式）

• 添加包：uv add requests (自动修改 pyproject.toml 并安装)。
• 添加开发依赖：uv add --dev pytest。
• 同步环境：uv sync (根据声明文件自动补全缺少的包，删除多余的包)。
• 运行代码：uv run main.py (无需激活环境，直接调用项目依赖运行)。
• 谨慎使用uv sync！：会干掉vs code中自动配置好的jupyter环境，导致侧边栏需要重新下载配套才能运行。当然项目里如果不需要jupyter扩展的侧边栏则无所谓。

5. 从旧项目迁移 (pip 迁移)

1. 清理旧环境：删除旧的 .venv 文件夹，删除 requirements.txt。
2. 生成声明文件：若无 pyproject.toml，运行 uv init。
3. 清爽导入：不要直接导入 pip freeze 的结果。手动在 pyproject.toml 中填写你核心直接使用的包（如 matplotlib、numpy），然后运行 uv sync。

6. 疑难解答 (FAQ)

Q1: 为什么安装时显示 warning: Failed to hardlink files？

• 原因：Windows 不支持跨硬盘分区（如从 C 盘到 D 盘）创建硬链接。
• 解决：将环境变量 UV_CACHE_DIR 设置在项目所在的同一个分区（详见 2.2 节）。设置后重启终端，运行 uv sync --reinstall 即可恢复性能。

Q2: uv init 和 uv venv 有什么区别？

• uv init：项目级概念。它创建 pyproject.toml，定义这个文件夹是一个 Python 项目，包含名字、版本等信息。
• uv venv：工具级概念。它只创建一个纯净的 .venv 虚拟环境。
• 建议：开发正式项目请始终使用 uv init 开始。

Q3: Python 解释器在 C 盘，项目在 D 盘，会影响性能吗？

• 结论：不会。
• 原理：uv 在项目里创建的是轻量级的“蹦床引导程序（Shim）”，只有几十 KB，跨磁盘调用 Python 核心极其高效。真正占用空间的库文件（Packages）则会通过硬链接保留在 D 盘，实现性能最大化。

Q4: 为什么 Installing wheels [0/1] 进度条不动就结束了？

• 结论：这通常是 UI 显示残留，不代表失败。
• 原因：当出现 Warning 弹窗或安装速度极快（1-2秒）时，终端刷新频率跟不上。只要看到 + package_name==version 绿色字样，就代表安装成功。

Q5: 切换到 uv 后，每个项目都要下载一份 Python 吗？

• 结论：不需要。
• 原理：uv 将所有下载的 Python 版本统一管理在系统中。一个项目声明使用 3.12，uv 只是将该项目里的启动器指向全局唯一的 3.12 安装目录。

Q6: 为什么我的 pyproject.toml 里多出很多看不懂的包？

• 原因：这是因为你之前使用了 pip freeze 生成的 requirements.txt 进行迁移。
• 解决建议：手动删除 pyproject.toml 中那些你没有直接 import 的包（它们是底层依赖），然后执行 uv sync。uv 会自动在 uv.lock 中维护它们，保持配置文件清爽。