📚 课程目录第2章开发环境搭建

2. 开发环境搭建

说实话，环境搭建往往是整个项目里最磨人的环节。我记得第一次做人脸识别项目时，光装 dlib 就折腾了大半天。但别怕，这一章我会把那些坑都指出来，你跟着走就行。

2.1 Python虚拟环境：为什么必须用？

你想想看，一个项目要 OpenCV 4.5，另一个要 3.4，如果全装全局环境，迟早乱套。虚拟环境就是给每个项目一个独立的小房间，互不干扰。

我个人习惯用 venv，Python 3.3+ 自带，不用额外装。

核心原则：每个项目一个虚拟环境，不要复用。我见过有人一个环境装十几个项目依赖，最后升级一个库崩一片。

创建虚拟环境

# 进入项目目录
cd attendance_system

# 创建虚拟环境（命名为 venv 是惯例）
python -m venv venv

# 激活（Windows）
venv\Scripts\activate

# 激活（macOS/Linux）
source venv/bin/activate

激活后，终端前面会出现 (venv) 字样，说明你已经在虚拟环境里了。

小技巧：我习惯在项目根目录建一个 requirements.txt，每次装完库就 pip freeze > requirements.txt，方便别人一键复现环境。

2.2 OpenCV库安装与验证

OpenCV 是人脸识别的眼睛。没有它，摄像头数据读不出来，图像处理也做不了。

安装命令

pip install opencv-python
pip install opencv-contrib-python  # 包含额外模块

为什么装两个？opencv-python 是核心库，opencv-contrib-python 包含一些实验性功能，比如人脸检测的 LBPH 算法。我建议两个都装，省得后面缺模块。

验证安装

python -c "import cv2; print(cv2.__version__)"

如果输出类似 4.8.0，说明安装成功。

踩坑记录：我曾经在 macOS 上遇到 OpenCV 装完后无法显示窗口的问题。原因是系统缺少 GUI 后端。解决方案：pip install opencv-python-headless 换成带 GUI 支持的版本，或者安装 pyqt5。

快速测试摄像头

import cv2

cap = cv2.VideoCapture(0)
if not cap.isOpened():
    print("摄像头打开失败")
else:
    ret, frame = cap.read()
    if ret:
        cv2.imwrite("test.jpg", frame)
        print("拍照成功")
    cap.release()

跑一下这段代码，如果能生成 test.jpg，说明 OpenCV 和摄像头都正常。

2.3 Face Recognition库安装与踩坑记录

这个库封装了 dlib 的人脸识别功能，用起来很方便。但安装过程……嗯，有点考验耐心。

标准安装

pip install face-recognition

如果一切顺利，你会看到一堆编译输出，最后显示安装成功。但现实往往没那么顺利。

常见错误：

CMake must be installed — 缺少 CMake 编译工具
dlib installation failed — dlib 编译失败
Microsoft Visual C++ 14.0 is required — Windows 缺少 C++ 编译环境

踩坑记录：Windows 环境

我曾经在 Windows 10 上装 face-recognition，卡在 dlib 编译上整整两个小时。最后发现是 Visual Studio 版本不对。

解决方案：

安装 Visual Studio Build Tools 2019（或更高版本）
安装时勾选「C++ 生成工具」和「Windows 10 SDK」
重启终端，重新执行 pip install face-recognition

省力方案：如果不想折腾编译，可以直接装预编译的 dlib：pip install dlib-bin（仅限 Windows）。但注意版本可能不是最新的。

踩坑记录：macOS 环境

macOS 上常见的问题是缺少 Xcode Command Line Tools。运行以下命令安装：

xcode-select --install

如果还报错，试试用 Homebrew 安装 cmake：

brew install cmake

验证安装

python -c "import face_recognition; print(face_recognition.__version__)"

如果输出版本号，恭喜你，最难的一关过了。

2.4 dlib依赖问题解决

dlib 是 face-recognition 的底层引擎，也是整个环境搭建的「鬼门关」。大部分安装失败都跟它有关。

为什么 dlib 这么难装？

说白了，dlib 是用 C++ 写的，安装时需要从源码编译。编译过程会调用 CMake，然后链接各种底层库。任何一个环节出问题，都会报错。

错误信息	原因	解决方案
`CMake must be installed`	缺少 CMake 编译工具	`pip install cmake` 或系统包管理器安装
`No module named 'dlib'`	dlib 未成功安装	检查编译日志，确认错误原因
`fatal error: 'Python.h' not found`	缺少 Python 开发头文件	安装 python3-dev（Linux）或 Xcode CLT（macOS）
`error: Microsoft Visual C++ 14.0 is required`	Windows 缺少 C++ 编译器	安装 Visual Studio Build Tools

终极解决方案：预编译包

如果实在编译不过，可以用预编译的 dlib。我推荐两个来源：

Windows：pip install dlib-bin（非官方，但稳定）
macOS/Linux：用 conda 安装 conda install -c conda-forge dlib

注意：预编译包可能不是最新版本，但功能完整。对于本课程来说，dlib 19.22+ 完全够用。不要为了追新版本浪费时间。

验证 dlib 安装

python -c "import dlib; print(dlib.__version__)"

如果输出版本号，说明 dlib 安装成功。这时候再装 face-recognition 就不会卡了。

2.5 环境验证总脚本

我习惯写一个验证脚本，一键检查所有依赖是否就绪。省得后面跑项目时才发现缺东西。

import sys
import cv2
import dlib
import face_recognition

print("Python 版本:", sys.version)
print("OpenCV 版本:", cv2.__version__)
print("dlib 版本:", dlib.__version__)
print("face_recognition 版本:", face_recognition.__version__)

# 检查摄像头
cap = cv2.VideoCapture(0)
if cap.isOpened():
    print("摄像头状态: 正常")
    cap.release()
else:
    print("摄像头状态: 未检测到")

print("环境验证完成！")

保存为 check_env.py，运行后如果所有版本都显示正常，说明环境搭建成功。

2.6 本章知识结构

下面这张图帮你理清整个环境搭建的脉络：

2.7 常见问题速查

最后，我把最常遇到的几个问题整理成表格，方便你快速定位：

问题	现象	快速解决
pip 安装超时	下载到一半卡住	`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名`
dlib 编译报错	红色错误日志一大片	先装 cmake，再装 Visual Studio Build Tools
OpenCV 无法打开摄像头	`cap.isOpened()` 返回 False	检查摄像头驱动，或换 USB 接口
face_recognition 导入报错	`ModuleNotFoundError`	确认 dlib 已安装，重新执行 `pip install face-recognition`