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，按回车打开终端。
复制并粘贴以下命令，按回车运行（三选一）：
- 如果有魔法：
  powershell 复制代码
```
irm https://astral.sh/uv/install.ps1 | iex
```
- 如果你电脑上已经安装了 Python，也可以直接通过镜像站下载：
  powershell 复制代码
```
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 窗口。
验证安装：
powershell 复制代码
```
uv --version
```
(如果看到版本号，说明安装成功)
配置国内镜像源

由于官方源服务器在国外，为了解决下载速度慢、连接超时的问题，建议配置 uv 使用国内镜像源（清华源）。

请直接复制下方所有代码，在 PowerShell 终端中一次性粘贴并回车运行：
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 内置终端。
在终端依次输入以下命令：
- 初始化项目 ：
  powershell 复制代码
```
uv init
```
- 修改.toml文件 ：
  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 ：
  powershell 复制代码
```
uv python pin 3.10
```
  (uv 会自动为你下载并管理 Python 3.10，无需你去官网下载)

🔵 第三步：安装 OpenCV

继续在终端中输入

powershell 复制代码

uv add opencv-python

(uv 会自动创建虚拟环境 .venv 文件夹，并将 OpenCV 及其依赖（如 NumPy）安装进去)

🟣 第四步：进阶理解 (配置文件与同步)

在使用 uv 时，理解以下两个概念非常重要。

1. 核心配置文件：pyproject.toml

当你执行 uv init 和 uv add 后，根目录下会自动生成一个 pyproject.toml 文件。这就是你的"项目说明书"。

示例文件内容如下：

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 文件夹。

此时，只需运行：
powershell 复制代码
```
uv sync
```
uv 会自动读取配置文件，下载 Python，安装所有依赖，一键配好环境。
场景二：手动修改了配置文件

如果你手动打开 pyproject.toml，在 dependencies 里加了一行 "requests"，保存后环境里并不会自动有这个包。

此时，运行：
powershell 复制代码
```
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 文件，内容如下：

python 复制代码

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:
        # 创建一个 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()

运行代码

在终端输入：

powershell 复制代码

uv run main.py

预期结果

text 复制代码

------------------------------
Python 版本: 3.10.x
OpenCV 版本: 4.x.x
✅ NumPy 配合正常，虚拟图像创建成功。
------------------------------

By: Balrog-v