最近在尝试使用 MediaPipe 进行计算机视觉开发时，遇到了一个让人头疼的错误：module 'mediapipe' has no attribute 'solutions'。经过一番折腾，终于找到了解决方案，这里把完整的排查和解决过程记录下来，希望对遇到同样问题的朋友有所帮助。

1. 错误分析：为什么会出现这个错误？

这个错误通常发生在以下几种情况：

• 安装的 MediaPipe 版本不完整：可能是 pip 安装过程中网络问题导致部分组件未正确安装
• 版本不兼容：Python 版本或系统环境与 MediaPipe 版本不匹配
• 命名空间冲突：项目中可能有其他名为 mediapipe 的模块或文件
• 错误的导入方式：尝试从错误的模块路径导入 solutions

2. 环境配置检查清单

在开始解决问题前，我们需要先确认基础环境：

1. Python 版本：MediaPipe 要求 Python 3.7-3.10（推荐 3.8+）
2. pip 版本：建议使用最新版 pip install --upgrade pip
3. 操作系统：确认是否支持（Windows/Linux/macOS）
4. 虚拟环境：建议使用 venv 或 conda 创建独立环境

可以通过以下命令检查环境：

import sys
print(f"Python版本: {sys.version}")
print(f"系统平台: {sys.platform}")

3. 安装方式对比：pip vs 源码编译

pip 直接安装（推荐大多数用户）

pip install mediapipe

优点： - 简单快捷 - 自动处理依赖 - 适合大多数开发场景

源码编译安装（高级用户）

git clone https://github.com/google/mediapipe.git
cd mediapipe
python setup.py install

优点： - 可以自定义编译选项 - 获取最新功能 - 适合深度定制需求

4. 正确的导入和使用方法

下面是一个带异常处理的完整示例：

try:
    import mediapipe as mp
    from mediapipe.python.solutions import hands  # 显式导入子模块

    # 检查关键组件是否存在
    if not hasattr(mp, 'solutions'):
        raise ImportError("mediapipe 安装不完整，缺少 solutions 模块")

    # 实际使用示例
    with mp.solutions.hands.Hands(
        static_image_mode=False,
        max_num_hands=2,
        min_detection_confidence=0.5) as hands_model:
        print("MediaPipe 成功初始化！")

except ImportError as e:
    print(f"导入错误: {e}")
    print("请尝试: pip install --upgrade mediapipe")
except Exception as e:
    print(f"运行时错误: {e}")

5. 常见问题及解决方案

1. 问题：安装后依然报错 解决：先卸载再重新安装 pip uninstall mediapipe && pip install mediapipe

2. 问题：与其他库冲突 解决：使用虚拟环境隔离

3. 问题：特定版本需求 解决：指定版本安装 pip install mediapipe==0.8.9.1

4. 问题：Windows 平台报错 解决：可能需要安装 Visual C++ 可再发行组件

5. 问题：ARM 架构支持 解决：使用 pip install mediapipe-silicon（M1 Mac）

6. 验证安装是否成功

运行以下测试脚本验证完整功能：

import mediapipe as mp

def test_mediapipe():
    required_modules = [
        'solutions',
        'solutions.hands',
        'solutions.face_mesh',
        'solutions.pose'
    ]

    for module in required_modules:
        try:
            attr = mp
            for part in module.split('.'):
                attr = getattr(attr, part)
            print(f"√ {module} 存在")
        except AttributeError:
            print(f"× {module} 缺失")

    print("\n基本功能测试完成！")

if __name__ == '__main__':
    test_mediapipe()

延伸阅读

1. MediaPipe 官方文档
2. GitHub Issues 常见问题
3. PyPI 版本历史

通过以上步骤，应该能解决大部分 module 'mediapipe' has no attribute 'solutions' 的问题。如果仍有疑问，建议查看官方 GitHub 的 Issues 板块，很多类似问题已经有详细讨论。希望这篇指南能帮你节省排查时间，让开发更高效！