快速搭建 uv 开发环境：创建虚拟环境 + 导入 requirements-dev.txt 依赖

在团队协作或新设备部署时，复用开发环境是提高效率的关键。如果已经有现成的 requirements-dev.txt 开发依赖清单，结合 uv 包管理器的高效特性，只需3步就能快速搭建一致的开发环境------无需复杂配置，兼顾速度与兼容性。本文将详细介绍跨平台的完整操作流程，适用于 Windows、macOS、Linux 系统。

一、前置准备：安装 uv 包管理器

首先确保本地已安装 uv（若未安装，执行以下命令快速安装）：

# 通用安装命令（Python 3.7+ 兼容）
pip install uv --upgrade

# 官网推荐安装方式（可选，更高效）
# Windows (PowerShell)
(Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -UseBasicParsing).Content | PowerShell -NoProfile
# macOS/Linux (bash)
curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，可通过 uv --version 验证是否安装成功（显示版本号即正常）。

二、完整操作流程（3步搞定）

第一步：创建 uv 虚拟环境

uv 创建虚拟环境的命令简洁高效，支持自定义环境名和存储路径：

核心命令格式

# 基础用法：创建名为 [环境名] 的虚拟环境（默认存储在 ~/.cache/uv/virtualenvs/）
uv venv [环境名]

# 自定义路径：在项目根目录创建虚拟环境（推荐，方便管理）
uv venv ./[环境目录名]

实操示例（推荐指定环境名，如 heli）

# 示例1：创建名为 heli 的虚拟环境（默认路径）
uv venv heli

# 示例2：在当前项目根目录创建 venv 文件夹（虚拟环境）
uv venv ./venv

关键说明：

• 执行后，uv 会自动匹配当前系统的 Python 版本，创建兼容的虚拟环境，并内置最新版 pip；

• 若环境已存在，会提示 Virtual environment already exists，可删除旧环境后重新创建，或用 --force 强制覆盖：

  uv venv heli --force  # 强制覆盖已存在的 heli 环境

第二步：激活 uv 虚拟环境

创建环境后必须激活，后续安装的依赖才会存入该环境（不同系统激活命令不同，务必对应）：

操作系统	终端类型	激活命令（以默认路径的 heli 环境为例）
Windows	PowerShell	~/.cache/uv/virtualenvs/heli/Scripts/Activate.ps1
Windows	CMD	%USERPROFILE%\.cache\uv\virtualenvs\heli\Scripts\activate.bat
macOS/Linux	bash/zsh/fish	source ~/.cache/uv/virtualenvs/heli/bin/activate

自定义路径激活示例（如环境在项目根目录 ./venv）：

# Windows (PowerShell)
./venv/Scripts/Activate.ps1

# macOS/Linux (bash)
source ./venv/bin/activate

激活验证：

终端提示符前会显示环境名（如 (heli) 或 (venv)），表示激活成功，此时所有 Python/pip/uv 命令都指向当前虚拟环境。

第三步：导入 requirements-dev.txt 依赖

确保 requirements-dev.txt 已在当前工作目录（或指定绝对路径），执行以下命令快速安装所有依赖：

核心命令（优先用 uv，速度比 pip 快 10-100 倍）

# uv 安装（兼容 pip 格式的 requirements 文件，推荐）
uv install -r requirements-dev.txt

# 备选：pip 安装（兼容所有场景，速度稍慢）
pip install -r requirements-dev.txt

路径说明：

• 若 requirements-dev.txt 在其他目录，需指定完整路径，例如：

  # Windows 绝对路径示例
  uv install -r D:\projects\my-project\requirements-dev.txt
  
  # macOS/Linux 绝对路径示例
  uv install -r ~/projects/my-project/requirements-dev.txt

安装过程说明：

• uv 会自动解析依赖清单，下载并安装指定版本的包，同时处理依赖冲突（若有冲突会给出明确提示）；
• 安装完成后，终端会显示 Installed X packages 确认安装成功。

三、验证依赖安装结果

安装完成后，可通过以下命令验证依赖是否正确导入：

# 方式1：用 uv 列出当前环境依赖（简洁清晰）
uv list

# 方式2：用 pip 列出依赖（兼容习惯）
pip list

# 方式3：检查特定依赖是否安装（如 pytest）
uv list pytest  # 或 pip show pytest

若能在输出中看到 requirements-dev.txt 中的所有包（如 pytest、black、flake8 等），且版本与文件中一致，则说明导入成功。

四、实用技巧与常见问题

1. 自定义虚拟环境路径（推荐项目内管理）

将虚拟环境放在项目根目录（如 ./venv），方便团队共享环境配置（可在 .gitignore 中添加 venv/ 避免提交到仓库）：

# 创建项目内虚拟环境
uv venv ./venv

# 激活（Windows PowerShell）
./venv/Scripts/Activate.ps1

# 激活（macOS/Linux）
source ./venv/bin/activate

2. 解决依赖版本冲突

若安装时提示版本冲突（如 A 包需 B 包 >=2.0，C 包需 B 包 <=1.0），可通过以下方式处理：

• 手动编辑 requirements-dev.txt，调整冲突包的版本号（优先选择兼容的中间版本）；
• 用 uv 的自动解决冲突功能：uv install -r requirements-dev.txt --resolve（uv 会尝试找到最优兼容版本）。

3. 离线安装依赖（无网络环境）

若需在无网络环境搭建，可先在有网络的机器上下载依赖包，再离线导入：

# 第一步：在有网络环境下载依赖包到本地目录（如 ./deps）
uv pip download -r requirements-dev.txt -d ./deps

# 第二步：拷贝 ./deps 和 requirements-dev.txt 到无网络机器，执行离线安装
uv install -r requirements-dev.txt --no-index --find-links ./deps

4. 退出虚拟环境

完成开发后，可执行以下命令退出当前虚拟环境：

deactivate  # 所有系统通用命令

五、快速复制命令集（直接粘贴使用）

Windows（PowerShell + 环境名 heli）

# 1. 安装 uv（若未安装）
pip install uv --upgrade

# 2. 创建虚拟环境
uv venv heli

# 3. 激活环境
~/.cache/uv/virtualenvs/heli/Scripts/Activate.ps1

# 4. 导入依赖（假设 requirements-dev.txt 在当前目录）
uv install -r requirements-dev.txt

macOS/Linux（bash + 项目内 venv 环境）

# 1. 安装 uv（若未安装）
pip install uv --upgrade

# 2. 创建项目内虚拟环境
uv venv ./venv

# 3. 激活环境
source ./venv/bin/activate

# 4. 导入依赖
uv install -r requirements-dev.txt

六、总结

通过「创建 uv 虚拟环境 → 激活环境 → 导入依赖」的三步流程，能快速复用 requirements-dev.txt 中的开发环境配置，核心优势如下：

1. 速度快：uv 安装依赖的速度远超传统 pip，尤其适合依赖较多的项目；
2. 兼容性强：支持 pip 格式的 requirements 文件，无需修改现有依赖清单；
3. 跨平台：Windows/macOS/Linux 命令统一，团队协作无阻碍。

无论你是新设备搭建环境，还是团队共享开发配置，这套流程都能帮你高效完成环境复用，避免"本地能跑，线上报错"的问题。