#【Windows 实战】
一、安装 uv（3 种方案）
✅ 方案 A：官方脚本（推荐）
自动下载二进制文件并配置环境变量。
```cmd
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
> **注意**：若报错 `ExecutionPolicy`，请先执行：
> ```cmd
> powershell -c "Set-ExecutionPolicy RemoteSigned -Scope CurrentUser"
> ```
✅ 方案 B：手动下载（无权限/公司电脑）
-
下载 `uv-x86_64-pc-windows-msvc.zip`
-
解压到固定目录（如 `C:\Users\YourName\.uv\bin`）
-
**将该目录加入系统 `Path` 环境变量**
-
重启 CMD 验证：`uv --version`
✅ 方案 C：pip 安装（不推荐）
```cmd
pip install uv
```
> 缺点：无法使用 `uv self update` 更新自身，功能受限。
二、更新 uv
根据安装方式不同，更新命令不同：
| 安装方式 | 更新命令 |
| :--- | :--- |
| **官方脚本/二进制** | `uv self update` |
| **pip 安装** | `pip install -U uv` |
> 💡 推荐官方安装方式，更新更干净彻底。
三、Python 版本管理
`uv` 可自动下载并管理 Python 解释器，无需手动去官网下载。
```cmd
查看已安装版本
uv python list
安装指定版本
uv python install 3.11
创建项目时指定
uv init myproject --python 3.11
为当前项目固定版本（生成 .python-version）
uv python pin 3.11
临时指定版本运行
uv run --python 3.12 python script.py
```
四、虚拟环境与环境激活
`uv` 摒弃了传统的 `activate` 脚本，改用 `uv run` 自动接管。
```cmd
创建虚拟环境（默认 .venv）
uv venv
创建时指定 Python 版本
uv venv --python 3.11
运行命令（自动激活环境，无需 source/activate）
uv run python main.py
uv run pytest
删除虚拟环境（直接删文件夹）
rmdir /s /q .venv
```
五、依赖安装与镜像源设置（关键）
❌ 常见误区
-
`uv` **不读取** `pip.ini` 配置文件。
-
`uv pip config` 命令在旧版本中不存在。
✅ 正确换源姿势（永久生效）
使用环境变量配置，适用于所有版本。
```cmd
setx UV_INDEX_URL "https://pypi.tuna.tsinghua.edu.cn/simple"
```
> **必须重启 CMD 后生效**。生效后可验证：`echo %UV_INDEX_URL%`
✅ 安装依赖
```cmd
兼容模式（适合旧项目迁移）
uv pip install -r requirements.txt
原生模式（推荐新项目，更快）
uv init
uv add requests pydantic # 生产依赖
uv add --dev pytest black # 开发依赖
uv sync # 一键安装并锁定
```
六、常见问题排查 (FAQ)
1. `uv` 命令找不到？
-
确认安装目录已加入 `Path`。
-
执行 `echo %PATH%` 检查，重启 CMD。
2. `warning: Failed to hardlink files`？
-
**原因**：缓存与项目不在同一磁盘分区，`uv` 自动降级为复制。
-
**解决**：不影响使用。想消除警告可设置：
```cmd
setx UV_LINK_MODE copy
```
3. 换源后仍慢？
-
检查环境变量是否生效。
-
确保网络可访问清华源（部分公司网络需代理）。
4. 如何卸载？
-
删除 `uv.exe` 文件。
-
删除 `%USERPROFILE%\.uv` 目录。
-
从 `Path` 环境变量中移除相关路径。
七、常用命令速查表
```cmd
=== 基础 ===
uv --version # 查看版本
uv self update # 更新 uv
uv help # 帮助文档
=== 项目与环境 ===
uv init <project> # 初始化项目
uv venv # 创建虚拟环境
uv run <cmd> # 在环境中运行命令
uv python install <ver> # 安装 Python 解释器
=== 依赖管理 ===
uv add <pkg> # 添加依赖
uv add --dev <pkg> # 添加开发依赖
uv remove <pkg> # 移除依赖
uv sync # 同步依赖 (安装)
uv pip install -r <file> # 兼容模式安装
=== 配置 ===
setx UV_INDEX_URL <url> # 设置镜像源 (永久)
setx UV_LINK_MODE copy # 设置链接模式 (消除警告)
```
总结
-
**独立工具**：`uv` 不是 `pip` 的补丁，配置需单独设置（特别是换源）。
-
**换源必做**：Windows 用户首选 `setx UV_INDEX_URL` 环境变量换源。
-
**原生模式**：新项目优先使用 `uv init` + `uv sync`，而非 `uv pip`。
-
**无需激活**：习惯使用 `uv run` 代替 `activate`。
> 现在，你的 Python 工作流，真的快了。
*本文基于 uv 0.5+ 版本，Windows 11 + CMD 环境实测。如遇版本差异，请以官方文档为准：https://docs.astral.sh/uv/\*