MediaPipe 与 NumPy 冲突：版本范围限制和二进制导入错误不能混为一谈

现象与适用范围

节点可能在 pip 解析依赖时被阻止，也可能装好后在导入原生扩展时失败。先读取当前 MediaPipe 发行包的依赖，不把历史版本的限制套到所有新版本。

检索片段；具体版本与异常上下文可能不同：

mediapipe
_ARRAY_API not found

已核对的依据

MediaPipe 官方 Python 安装说明 列出桌面平台和 python -m pip install mediapipe，没有给所有版本指定统一 NumPy 版本。2024 年问题报告 提到 MediaPipe 0.10.15 要求 numpy<2；而当前 PyPI 1.0.1 元数据及 wheel 列表 只声明 numpy，没有该上限，且 wheel 按平台区分。因此旧问题不能当作当前通用版本锁。NumPy 导入错误指南 将 _ARRAY_API not found 与 numpy.dtype size changed 列为可能的下游二进制不兼容，并建议从 traceback 找到首个非 NumPy 的失败包。

需要区分的情况

1. 确切 MediaPipe 发行版与另一依赖的 NumPy 范围没有交集，或 pip 找不到匹配解释器/平台的 wheel。

2. 安装完成，但某个下游原生扩展导入时出现 _ARRAY_API、dtype size changed 等 ABI 错误；失败扩展也可能是同一节点堆栈中的其他包。

3. 库和二进制扩展已能导入，失败发生在节点资源、图像格式或模型功能中。

建议的排查顺序

以下为本站编排的操作建议，不表示已定位你的具体环境。

1. 用启动 ComfyUI 的 Python 可执行文件记录 MediaPipe、NumPy、节点版本、解释器/架构、pip 选中的 wheel，以及解析错误或完整 traceback；先分清安装阶段与运行时导入。

2. 读取确切发行版的 Requires-Dist 并运行依赖检查，比较所有受影响消费者的版本范围；不能因为 0.10.15 的旧讨论就在共享环境全局写入 numpy<2。

3. 版本范围无交集时隔离工作负载。遇到 ABI 错误，按 NumPy 建议找 traceback 中第一个非 NumPy 的包，在可恢复副本里测试其维护中的兼容发行或文档化重建；避免不明二进制和反复整体重装。

4. 确切失败的导入通过后，用节点作者的最小无隐私输入验证，再回归其他依赖 NumPy 的节点。后续模型路径或图像格式错误属于另一阶段，不据此继续反复降级。

怎样判断这一层已解决

包依赖关系一致、相关原生模块可加载、最小节点任务完成，并且保留工作流未被破坏。

注意事项和适用边界

当前元数据宽泛的 numpy 声明，不证明共享 ComfyUI 环境中每个原生扩展都兼容所有 NumPy 构建；各平台 wheel 也不相同。依赖检查通过不能替代 ABI 与实际功能验证。

资料复核并独立审阅中文：2026-09-26。本站未安装包、导入原生模块、执行 MediaPipe 任务、GPU 推理或修复用户环境。

原始来源

• MediaPipe Python setup · 2026-09-26
• MediaPipe issue 5676: historical NumPy constraint · 2026-09-26
• MediaPipe PyPI release files · 2026-09-26
• NumPy import-error troubleshooting · 2026-09-26

相关排查

• ModuleNotFoundError：包已安装，ComfyUI 仍说找不到模块
• 修复 ComfyUI 前后该记什么：一份可复查的环境记录