根本原因是cffi编译需系统级libffi开发包，Ubuntu/Debian下必须安装libffi-dev（非libffi7），CentOS/RHEL下安装libffi-devel，macOS用brew install libffi，缺失头文件ffi.h导致编译失败。

为什么 cffi 安装失败时总报 “ffi.h not found”？

根本原因不是 Python 或 pip 本身的问题，而是 cffi 在编译阶段依赖系统级的 libffi 开发头文件（尤其是 ffi.h）和静态库。没有这些，setup.py 就无法生成 C 扩展模块——哪怕你已装了运行时的 libffi，只要没装 -dev 或 -devel 包，就会卡在编译环节。

Ubuntu/Debian 系统下该装哪个包？

必须安装 libffi-dev，不是 libffi7 或其他运行时包。常见错误是只运行 apt install libffi7，这完全无效。

• apt update && apt install libffi-dev
• 装完后验证：dpkg -L libffi-dev | grep ffi.h 应输出类似 /usr/include/x86_64-linux-gnu/ffi.h
• 如果用的是非标准架构（如 arm64），包名一致，但路径中架构名会变

CentOS/RHEL/Fedora 怎么处理？

对应包名是 libffi-devel，不是 libffi。RHEL 8+ 和 CentOS Stream 默认启用 powertools 或 crb 仓库，需先确保它已启用。

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• CentOS 7 / RHEL 7：yum install libffi-devel
• RHEL 8+ / CentOS Stream：dnf install libffi-devel（若提示找不到，先运行 dnf config-manager --set-enabled crb）
• Fedora：dnf install libffi-devel

macOS 上用 Homebrew 装错包也会失败

Homebrew 的 libffi 包默认包含头文件，但如果你之前手动删过 /opt/homebrew/include/ffi.h 或升级出错，cffi 仍会报错。别碰 libffi 的 symlink，也别装 libffi@x.x 这类版本化别名包——它们不提供标准头文件路径。

• 正确操作：brew install libffi（确保无报错）
• 检查：find /opt/homebrew -name "ffi.h" 2>/dev/null（Intel）或 /opt/homebrew（Apple Silicon）
• 若 pip install cffi 仍失败，临时加环境变量：export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"

注意：Windows 用户基本不会遇到这个问题，因为 cffi 的 Windows wheel 是预编译好的，不触发本地构建。真正要小心的是 WSL 用户——他们用的是 Linux 发行版逻辑，得按 Ubuntu/CentOS 方式处理。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！