Windows 下使用 uv 从零配置 Python (OpenCV) 环境指南
本文档适用于在一台全新的 Windows 电脑上，使用 uv 快速配置vscode + Python 3.10 开发环境，并安装 OpenCV 库。同时包含关于 uv 的进阶说明。
B站配套视频 2026最新：使用uv管理python&opencv
🟢 第一步：安装 uv 包管理器
既然电脑上什么都没有，我们需要先安装这个核心工具。
按下 Win + R 键，输入 powershell，按回车打开终端。
复制并粘贴以下命令，按回车运行（三选一）：
- 如果有魔法：irm https://astral.sh/uv/install.ps1 | iex
- 如果你电脑上已经安装了 Python，也可以直接通过镜像站下载：pip install uv –i https://pypi.tuna.tsinghua.edu.cn/simple
- 或者进如 uv 下载链接 找到 uv-x86_64-pc-windows-msvc.zip 下载解压后，将包含 uv.exe 的文件夹路径（例如 D:\\tools\\uv）添加到系统环境变量的 Path 中。
安装完成后，关闭并重新打开 PowerShell 窗口。
验证安装：
uv —version
(如果看到版本号，说明安装成功)
配置国内镜像源 由于官方源服务器在国外，为了解决下载速度慢、连接超时的问题，建议配置 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 全局下载配置即已更新为清华源。
🟡 第二步：创建项目并初始化
我们不使用全局环境，而是为每个项目创建一个独立环境（这是最佳实践）。
在电脑上新建一个文件夹（例如 my-opencv-project）。
打开 VS Code。
点击菜单栏 File (文件) -> Open Folder (打开文件夹)，选择刚才新建的文件夹。
使用快捷键 Ctrl + ~ (Esc 下面那个波浪号键) 打开 VS Code 内置终端。
在终端依次输入以下命令：
- 初始化项目：uv init
- 修改.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",
] - 指定 Python 版本为 3.10：uv python pin 3.10
(uv 会自动为你下载并管理 Python 3.10，无需你去官网下载)
🔵 第三步：安装 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？
-
场景一：刚下载别人的代码 你从 GitHub 上克隆了一个项目，或者同学发给你一个压缩包。你电脑上还没有 .venv 文件夹。 此时，只需运行：
uv sync
uv 会自动读取配置文件，下载 Python，安装所有依赖，一键配好环境。
-
场景二：手动修改了配置文件 如果你手动打开 pyproject.toml，在 dependencies 里加了一行 "requests"，保存后环境里并不会自动有这个包。 此时，运行：
uv sync
uv 会检测到变化，并把 requests 安装进去。
🔴 第五步：配置 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
def main():
print("-" * 30)
print(f"Python 版本: {sys.version.split()[0]}")
print(f"OpenCV 版本: {cv2.__version__}")
# 测试 NumPy (OpenCV 通常会自动安装它)
try:
# 创建一个 100×100 的黑色图像
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
