2026最新保姆级教程：Windows 下使用 uv 从零配置 Python (OpenCV) 环境指南
Windows 下使用 uv 从零配置 Python (OpenCV) 环境指南
本文档适用于在一台全新的 Windows 电脑上，使用uv快速配置vscode + Python 3.10 开发环境，并安装 OpenCV 库。同时包含关于uv的进阶说明。
B站配套视频 2026最新：使用uv管理python&opencv
🟢 第一步：安装 uv 包管理器
既然电脑上什么都没有，我们需要先安装这个核心工具。
- 按下
Win + R键，输入powershell，按回车打开终端。 - 复制并粘贴以下命令，按回车运行（三选一）：
- 或者进如 uv 下载链接 找到
uv-x86_64-pc-windows-msvc.zip下载解压后，将包含uv.exe 的文件夹路径（例如 D:\tools\uv）添加到系统环境变量的 Path 中。
- 或者进如 uv 下载链接 找到
- 安装完成后，关闭并重新打开 PowerShell 窗口。
配置国内镜像源
由于官方源服务器在国外，为了解决下载速度慢、连接超时的问题，建议配置 uv 使用国内镜像源（清华源）。请直接复制下方所有代码，在 PowerShell 终端中一次性粘贴并回车运行：
# 1. 创建配置目录（如果不存在）New-Item-Path "$env:APPDATA\uv"-ItemType Directory -Force # 2. 写入配置内容到 uv.toml (使用清华源)$content = @" [[index]] url = "https://pypi.tuna.tsinghua.edu.cn/simple" default = true "@ Set-Content-Path "$env:APPDATA\uv\uv.toml"-Value $content运行完成后，您的 uv 全局下载配置即已更新为清华源。
验证安装：
uv --version (如果看到版本号，说明安装成功)
如果你电脑上已经安装了 Python，也可以直接通过镜像站下载：
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple 如果有魔法：
irm https://astral.sh/uv/install.ps1 |iex🟡 第二步：创建项目并初始化
我们不使用全局环境，而是为每个项目创建一个独立环境（这是最佳实践）。
- 在电脑上新建一个文件夹（例如
my-opencv-project）。 - 打开 VS Code。
- 点击菜单栏 File (文件) -> Open Folder (打开文件夹)，选择刚才新建的文件夹。
- 使用快捷键
Ctrl + ~(Esc 下面那个波浪号键) 打开 VS Code 内置终端。 - 在终端依次输入以下命令：
指定 Python 版本为 3.10：
uv python pin 3.10 (uv 会自动为你下载并管理 Python 3.10，无需你去官网下载)
修改.toml文件：
[project] name = "vision-winer-camp" version = "0.1.0" description = "Add your description here" requires-python = ">=3.10" dependencies = [ "opencv-python>=4.12.0.88", ] 初始化项目：
uv init 🔵 第三步：安装 OpenCV
继续在终端中输入
uv add opencv-python (uv 会自动创建虚拟环境 .venv 文件夹，并将 OpenCV 及其依赖（如 NumPy）安装进去)
🟣 第四步：进阶理解 (配置文件与同步)
在使用 uv 时，理解以下两个概念非常重要。
1. 核心配置文件：pyproject.toml
当你执行 uv init 和 uv add 后，根目录下会自动生成一个 pyproject.toml 文件。这就是你的“项目说明书”。
示例文件内容如下：
[project] name = "my-opencv-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.10" dependencies = [ "opencv-python>=4.10.0.84", ] 作用：这个文件告诉 uv，你的项目叫什么，需要什么 Python 版本，以及依赖哪些库。如果你把代码发给同学，他们只需要有这个文件，就能还原出和你一模一样的环境。
2. 环境同步命令：uv sync
uv sync 是 uv 中最强大的命令之一，它的作用是 “让你的虚拟环境 (.venv) 与 锁定文件 (uv.lock) 保持绝对一致”。
什么时候使用 uv sync？
场景二：手动修改了配置文件
如果你手动打开 pyproject.toml，在 dependencies 里加了一行 "requests"，保存后环境里并不会自动有这个包。
此时，运行：
uv sync uv 会检测到变化，并把 requests 安装进去。
场景一：刚下载别人的代码
你从 GitHub 上克隆了一个项目，或者同学发给你一个压缩包。你电脑上还没有 .venv 文件夹。
此时，只需运行：
uv sync uv 会自动读取配置文件，下载 Python，安装所有依赖，一键配好环境。
🔴 第五步：配置 VS Code 识别环境
虽然环境装好了，但 VS Code 可能还不知道。
- 检查右下角：
打开项目里的mian.py文件，看 VS Code 右下角是否显示3.10.x ('.venv': venv)。 - 手动选择 (如果没显示)：
- 按
Ctrl + Shift + P打开命令面板。 - 输入并选择
Python: Select Interpreter。 - 在列表中选择带有
('.venv')或Recommended字样的选项。
- 按
⚫ 第六步：编写代码测试
修改项目中的 main.py 文件，内容如下：
import cv2 import sys import numpy as np defmain():print("-"*30)print(f"Python 版本: {sys.version.split()[0]}")print(f"OpenCV 版本: {cv2.__version__}")# 测试 NumPy (OpenCV 通常会自动安装它)try:# 创建一个 100x100 的黑色图像 img = np.zeros((100,100,3), dtype=np.uint8)print("✅ NumPy 配合正常，虚拟图像创建成功。")except Exception as e:print(f"❌ 出错: {e}")print("-"*30)if __name__ =="__main__": main()运行代码
在终端输入：
uv run main.py 预期结果
------------------------------ Python 版本: 3.10.x OpenCV 版本: 4.x.x ✅ NumPy 配合正常，虚拟图像创建成功。 ------------------------------ By: Balrog-v
