pip install opencv-python卡在Building wheel本质是pip尝试源码编译，应中断后换清华镜像源重装：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ opencv-python，并确保使用正确venv路径、python -m pip安装及纯英文无空格项目路径。
pip install opencv-python 卡在 Building wheel
这是最常见现象，本质是 pip 尝试从源码编译，而不是下载预编译 wheel。Windows 上尤其容易卡在 Building wheel for opencv-python，然后超时或报错。
直接中断并换国内镜像源重装：
- 先按
Ctrl+C中断当前安装 - 运行：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ opencv-python - 不要用
opencv-contrib-python或opencv-python-headless替代——除非你明确不需要cv2.imshow()
PyCharm 显示 No module named 'cv2' 但终端能 import
说明 PyCharm 没绑定到你激活的 venv，或者解释器缓存没刷新。
必须做三件事：
立即学习“Python免费学习笔记（深入）”；
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
- 确认终端里
which python（macOS/Linux）或where python（Windows）输出路径，和 PyCharm 设置里的Python Interpreter路径完全一致（例如D:\project\venv\Scripts\python.exe） - 在 PyCharm 的
File > Settings > Project > Python Interpreter页面，点击右上角齿轮 →Show All→ 删除当前条目 →Add Interpreter > Existing Environment，重新选中那个python.exe - 重启 PyCharm 后执行
File > Invalidate Caches and Restart > Invalidate and Restart，否则补全和 import 检查可能仍失效
pip list 看不到 opencv-python，但 pip install 说“已满足要求”
典型环境错位：你在系统 Python 下执行了 pip install，但 venv 里没装；或者你在 venv 终端里装了，却忘了 activate 就直接运行命令。
验证和修复步骤：
- 先确保 venv 已激活：Windows 下运行
venv\Scripts\activate，Linux/macOS 下运行source venv/bin/activate，提示符应出现(venv) - 再运行：
python -m pip show opencv-python—— 如果报Package(s) not found，说明真没装 - 此时再装：
python -m pip install opencv-python（显式用python -m pip可避免调用错 pip）
路径含中文或空格导致 cv2 导入失败
比如项目在 D:\迅雷下载\myproj 或 C:\My Projects\cv-test，某些 OpenCV 版本（尤其是 4.8+）在加载 DLL 时会因路径 decode 失败而静默失败，不报错但 import cv2 就是失败。
这不是 bug，是底层 C 库对宽字符支持不一致。解决方式极简单：
- 把整个项目移到纯英文无空格路径下，例如：
D:\cvtest、C:\py\face-detect - 删掉旧 venv，重建：
python -m venv venv，再装 OpenCV - 别指望改环境变量或加编码声明来绕过——这属于 Windows API 层限制，绕不过
python.exe、是否用 python -m pip 而非裸 pip，这三个点漏掉任何一个，都会让安装看似成功实则无效。 
