【OpenCV 入门到精通 02】环境安装与第一个程序：5 分钟跑通 Hello OpenCV

标签：OpenCV安装 opencv-python pip conda Hello World

难度：⭐ 入门 | 阅读时长 ：约 45 分钟 | 系列：第 02/12 集

前置：01 认识 OpenCV | 下一集 ：03 图像入门

写在前面

工欲善其事，必先利其器。本集帮你在 Windows / Linux / macOS 上完成 OpenCV-Python 安装，并运行第一个程序------在窗口中显示一张图片。

本集学习目标

通过 pip/conda 安装 opencv-python
理解 opencv-python 与 opencv-contrib-python 的区别
运行 Hello OpenCV 验证环境
了解常见安装问题及解决方案

文章目录

[【OpenCV 入门到精通 02】环境安装与第一个程序：5 分钟跑通 Hello OpenCV](#【OpenCV 入门到精通 02】环境安装与第一个程序：5 分钟跑通 Hello OpenCV)
- 写在前面
- 本集学习目标
- [2.1 系统要求](#2.1 系统要求)
- [2.2 pip 安装（推荐）](#2.2 pip 安装（推荐）)
- - [同时安装 NumPy（通常自动安装）](#同时安装 NumPy（通常自动安装）)
- [2.3 conda 安装](#2.3 conda 安装)
- [2.4 opencv-python vs opencv-contrib-python](#2.4 opencv-python vs opencv-contrib-python)
- - [contrib 额外提供的算法](#contrib 额外提供的算法)
- [2.5 Hello OpenCV](#2.5 Hello OpenCV)
- [2.6 完整验证脚本](#2.6 完整验证脚本)
- [2.7 踩坑指南](#2.7 踩坑指南)
- - 中文路径读取方案
- [2.8 常见问题 FAQ](#2.8 常见问题 FAQ)
- [2.9 本集小结](#2.9 本集小结)

2.1 系统要求

组件	最低	推荐
Python	3.6+	3.10 / 3.11
内存	4 GB	8 GB+
系统	Win7+ / Ubuntu16+ / macOS10+	最新稳定版

2.2 pip 安装（推荐）

bash 复制代码

# 标准版（覆盖 90% 学习需求）
pip install opencv-python

# 国内镜像加速
pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

# 锁定版本（生产环境）
pip install opencv-python==4.9.0.80

同时安装 NumPy（通常自动安装）

bash 复制代码

pip install numpy opencv-python

2.3 conda 安装

bash 复制代码

conda create -n opencv python=3.11 -y
conda activate opencv
conda install -c conda-forge opencv
# 或
pip install opencv-python

2.4 opencv-python vs opencv-contrib-python

包名	内容	适用
opencv-python	核心模块	学习、一般项目
opencv-contrib-python	核心 + 扩展模块	需要 SIFT/SURF 等专利算法

⚠️ 两者不可同时安装，后者会覆盖前者。

contrib 额外提供的算法

算法	模块
SIFT	features2d
SURF	features2d
FAST	features2d
背景减除高级算法	bgsegm

bash 复制代码

# 需要 SIFT 等扩展算法时
pip uninstall opencv-python
pip install opencv-contrib-python

2.5 Hello OpenCV

第一个程序

python 复制代码

import cv2
import numpy as np

# 创建 300×500 的蓝色画布 (BGR)
img = np.zeros((300, 500, 3), dtype=np.uint8)
img[:] = (255, 128, 0)  # 蓝色

# 写文字
cv2.putText(img, "Hello OpenCV!", (80, 160),
            cv2.FONT_HERSHEY_SIMPLEX, 1.2, (255, 255, 255), 2)

# 显示
cv2.imshow("Hello OpenCV", img)
print("按任意键关闭窗口...")
cv2.waitKey(0)
cv2.destroyAllWindows()

读取并显示真实图片

python 复制代码

import cv2

img = cv2.imread("test.jpg")
if img is None:
    print("图片读取失败，请检查路径")
else:
    print(f"图片尺寸: {img.shape}")
    cv2.imshow("Image", img)
    cv2.waitKey(0)
    cv2.destroyAllWindows()

代码解剖

函数	作用
`cv2.imread()`	读取图片 → NumPy 数组
`cv2.imshow()`	在窗口显示
`cv2.waitKey(0)`	等待按键（0=无限等待）
`cv2.destroyAllWindows()`	关闭所有窗口

2.6 完整验证脚本

python 复制代码

"""OpenCV 环境验证脚本"""
import sys

def check():
    print("=" * 50)
    print("OpenCV 环境验证")
    print("=" * 50)

    # 1. OpenCV
    try:
        import cv2
        print(f"✅ OpenCV {cv2.__version__}")
    except ImportError:
        print("❌ 未安装 → pip install opencv-python")
        return False

    # 2. NumPy
    try:
        import numpy as np
        print(f"✅ NumPy {np.__version__}")
    except ImportError:
        print("❌ 未安装 → pip install numpy")
        return False

    # 3. 创建测试图
    try:
        img = np.zeros((100, 200, 3), dtype=np.uint8)
        img[:] = (0, 255, 0)
        assert img.shape == (100, 200, 3)
        print("✅ 图像创建正常")
    except Exception as e:
        print(f"❌ 图像操作失败: {e}")
        return False

    # 4. 编解码
    try:
        ok, buf = cv2.imencode(".png", img)
        decoded = cv2.imdecode(buf, cv2.IMREAD_COLOR)
        assert decoded is not None
        print("✅ 图像编解码正常")
    except Exception as e:
        print(f"❌ 编解码失败: {e}")
        return False

    # 5. GUI（无头环境可能跳过）
    try:
        cv2.imshow("_test", img)
        cv2.waitKey(1)
        cv2.destroyAllWindows()
        print("✅ GUI 窗口正常")
    except Exception:
        print("⚠️ GUI 不可用（服务器/无头环境正常）")

    print("=" * 50)
    print("🎉 环境验证通过！")
    return True

if __name__ == "__main__":
    sys.exit(0 if check() else 1)

2.7 踩坑指南

问题	原因	解决
`cv2.imshow` 无窗口	无 GUI 环境	服务器用 `cv2.imwrite` 保存
`ImportError: cv2`	未安装	`pip install opencv-python`
两个包装冲突	同时装了 python 和 contrib	卸载后只装一个
`imread` 返回 None	路径错误或中文路径	检查路径；用 `np.fromfile` 读中文路径
pip 安装慢	默认源慢	加清华镜像
ARM 架构安装失败	无预编译包	从源码编译或用 conda

中文路径读取方案

python 复制代码

import cv2
import numpy as np

def imread_chinese(path):
    """解决 OpenCV 无法读取中文路径的问题"""
    return cv2.imdecode(np.fromfile(path, dtype=np.uint8), cv2.IMREAD_COLOR)

img = imread_chinese("测试图片/风景.jpg")

2.8 常见问题 FAQ

Q1：opencv-python-headless 是什么？

A：无 GUI 版本，适合 Docker/服务器部署，不含 imshow 等窗口功能。

Q2：需要单独装 OpenCV C++ 吗？

A：不需要。pip install opencv-python 已包含编译好的二进制。

Q3：OpenCV 4.9 和 4.1 教程兼容吗？

A：核心 API 兼容，个别函数参数有微调，本系列以 4.x 通用写法为准。

2.9 本集小结

安装检查清单：

pip install opencv-python 成功
import cv2 无报错
Hello OpenCV 程序能弹窗显示
验证脚本通过

← 第01集	第03集：图像入门 →

参考：1_2 在Windows中安装OpenCV-Python