一、整体环境说明
设备：Intel芯片Mac（x86_64架构）
项目：AI测试代理后端项目
工具：uv虚拟环境管理、pyproject.toml管理依赖
核心冲突：新版PyTorch、OnnxRuntime已停止维护Intel Mac预编译包，高版本Python无法匹配旧兼容依赖
二、三次环境配置问题完整总结
第一次：初次搭建项目基础环境报错
博文地址：https://blog.csdn.net/m0_55845928/article/details/159732244
- 报错问题
安装onnxruntime==1.24.4失败，提示无当前平台可用安装包 - 报错原因
onnxruntime 1.17及以上高版本，不再提供Intel Mac(x86_64)架构预编译依赖包，无法直接安装 - 初期临时方案
尝试更换低版本onnxruntime，未彻底解决Python版本联动冲突，仅临时绕过报错
第二次：全局安装项目全部依赖报错
博文地址：https://blog.csdn.net/m0_55845928/article/details/161218615
- 报错问题
PyTorch依赖安装失败，无匹配Python版本标签，依赖版本解析不通过 - 报错原因
- 本机默认Python3.12，最后兼容Intel Mac的torch2.1.2仅支持最高Python3.11
- 高版本pymupdf4llm强制绑定高版本onnxruntime，形成连环依赖冲突
- 解决思路
确定核心适配组合：Python3.11 + torch2.1.2 + 低版本onnxruntime
第三次：uv虚拟环境内安装项目依赖报错
博文地址：https://blog.csdn.net/m0_55845928/article/details/161219771
- 报错问题
1）pyproject.toml配置语法错误，缺少括号导致解析失败
2）误用onnxruntime-silicon芯片专属包，该包仅适配苹果硅芯片，Intel设备无法使用
3）uv严格校验全平台、全Python版本兼容性，放大依赖冲突 - 报错原因
- TOML配置格式不规范
- 混淆Apple Silicon与Intel架构专属依赖包
- 未锁定Python版本，uv自动匹配高版本Python引发兼容校验失败
- 最终根治方案
统一锁定环境版本、规范配置、降级冲突依赖
三、最终统一完美环境配置（可直接用于项目）
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
四、核心避坑总结（重点）
- 架构区分避坑
onnxruntime-silicon只适用于M系列苹果芯片，Intel Mac绝对不能安装 - 版本绑定避坑
Intel Mac做AI项目，优先固定Python3.11，不要使用3.12及以上新版本 - 依赖降级避坑
PDF解析依赖pymupdf4llm必须降级，避免强制拉高onnxruntime版本 - 配置语法避坑
uv配置段必须写[tool.uv]，缺少中括号会直接配置解析失败 - 工具特性避坑
uv依赖校验比pip严格，必须提前锁定环境，否则极易出现平台不兼容报错
五、问题根源一句话总结
所有环境报错本质一致：Intel老旧Mac架构不再被主流AI库新版本适配，只能采用旧版稳定依赖+低版本Python组合完成项目环境搭建