一、整体环境说明

设备：Intel芯片Mac（x86_64架构）
项目：AI测试代理后端项目
工具：uv虚拟环境管理、pyproject.toml管理依赖
核心冲突：新版PyTorch、OnnxRuntime已停止维护Intel Mac预编译包，高版本Python无法匹配旧兼容依赖

二、三次环境配置问题完整总结

第一次：初次搭建项目基础环境报错

博文地址：https://blog.csdn.net/m0_55845928/article/details/159732244

1. 报错问题
   安装onnxruntime==1.24.4失败，提示无当前平台可用安装包
2. 报错原因
   onnxruntime 1.17及以上高版本，不再提供Intel Mac(x86_64)架构预编译依赖包，无法直接安装
3. 初期临时方案
   尝试更换低版本onnxruntime，未彻底解决Python版本联动冲突，仅临时绕过报错

第二次：全局安装项目全部依赖报错

博文地址：https://blog.csdn.net/m0_55845928/article/details/161218615

1. 报错问题
   PyTorch依赖安装失败，无匹配Python版本标签，依赖版本解析不通过
2. 报错原因

• 本机默认Python3.12，最后兼容Intel Mac的torch2.1.2仅支持最高Python3.11
• 高版本pymupdf4llm强制绑定高版本onnxruntime，形成连环依赖冲突

3. 解决思路
   确定核心适配组合：Python3.11 + torch2.1.2 + 低版本onnxruntime

第三次：uv虚拟环境内安装项目依赖报错

博文地址：https://blog.csdn.net/m0_55845928/article/details/161219771

1. 报错问题
   1）pyproject.toml配置语法错误，缺少括号导致解析失败
   2）误用onnxruntime-silicon芯片专属包，该包仅适配苹果硅芯片，Intel设备无法使用
   3）uv严格校验全平台、全Python版本兼容性，放大依赖冲突
2. 报错原因

• TOML配置格式不规范
• 混淆Apple Silicon与Intel架构专属依赖包
• 未锁定Python版本，uv自动匹配高版本Python引发兼容校验失败

3. 最终根治方案
   统一锁定环境版本、规范配置、降级冲突依赖

三、最终统一完美环境配置（可直接用于项目）

1. 统一环境规范

• 固定Python版本：3.11
• 固定适配依赖：Intel Mac最后兼容稳定版
• 关闭uv多余跨平台校验

2. 完整可用 pyproject.toml

https://blog.csdn.net/m0_55845928/article/details/161219771

3. 终端一键环境部署命令

https://blog.csdn.net/m0_55845928/article/details/161219771

四、核心避坑总结（重点）

1. 架构区分避坑
   onnxruntime-silicon只适用于M系列苹果芯片，Intel Mac绝对不能安装
2. 版本绑定避坑
   Intel Mac做AI项目，优先固定Python3.11，不要使用3.12及以上新版本
3. 依赖降级避坑
   PDF解析依赖pymupdf4llm必须降级，避免强制拉高onnxruntime版本
4. 配置语法避坑
   uv配置段必须写[tool.uv]，缺少中括号会直接配置解析失败
5. 工具特性避坑
   uv依赖校验比pip严格，必须提前锁定环境，否则极易出现平台不兼容报错

五、问题根源一句话总结

所有环境报错本质一致：Intel老旧Mac架构不再被主流AI库新版本适配，只能采用旧版稳定依赖+低版本Python组合完成项目环境搭建