python 3.11下pip install -r requirements.txt报错主因是子依赖未声明python_requires或使用已移除c api；应先用pipdeptree定位隐藏冲突，再核查pypi上带cp311后缀的wheel真实支持版本，并重点更新numpy≥1.23.5、pandas≥2.0.0等科学计算栈及importlib-metadata等间接依赖。
直接升级到 Python 3.11 后 pip install -r requirements.txt 报错，八成是某个子依赖没声明 python_requires 或用了已移除的 C API；别急着降级，先用 pipdeptree 挖出隐藏冲突点，再针对性替换或锁定版本。
查 PyPI 页面和 pip index versions 看清真实支持范围
很多包在 PyPI 上标了 Programming Language :: Python :: 3.11，但实际 wheel 文件可能只编译到 3.10。盲目信标签会踩坑。
- 运行
pip index versions some-package（需 pip ≥ 20.3），它返回的版本列表里带cp311后缀的才是真支持 3.11 的 wheel - 重点盯住科学计算栈：
numpy≥ 1.23.5、pandas≥ 2.0.0、scipy≥ 1.10.0；旧版 numpy 在 3.11 下会因 ABI 变更直接ImportError: undefined symbol: PyUnicode_AsUTF8AndSize - Web 框架如
flask≥ 2.2.0、fastapi≥ 0.95.0 才完整适配 3.11 的asyncio.TaskGroup和异常链优化
用 pipdeptree 暴露间接不兼容的子依赖
pip install -r requirements.txt 失败时只报最外层包，但真正卡住的往往是它的子依赖——比如 click 自己兼容 3.11，但它拉的 importlib-metadata ≤ 5.2 就会在 3.11 下崩溃。
- 先激活干净的 3.11 虚拟环境：
pyenv virtualenv 3.11.9 myproj-311 - 装完
pip install pipdeptree，再跑：pipdeptree --warn silence --python-executable $(which python) - 输出中带
unsatisfied标记的行就是问题源，例如：importlib-metadata==4.12.3 [requires: python_version >= "3.7"]→ 实际需要 ≥ 6.0 才能用 3.11 的sys.unraisablehook
警惕带 .so/.pyd 的 C 扩展包
像 ujson、orjson、psycopg2-binary 这类包，PyPI 上若没有 cp311 轮子，pip 会退回到源码编译——但很多旧版 setup.py 不认识 3.11 的 Py_SET_REFCNT 宏，直接 error: unknown type name 'PySetObject'。
- 检查方法：
pip show ujson | grep Version，再上 PyPI 查对应版本的 Files 标签页，确认有ujson-5.9.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl这类文件 - 若无，要么换纯 Python 替代（如用
json替ujson），要么手动升到最新版：pip install "ujson>=5.9.0" - 特别注意
mediapipe：官方明确只支持 3.8–3.11，3.12+ 直接不提供 wheel；3.11 环境下也得用mediapipe==0.10.14及以上才稳定
实测 importtime 和 pyperf，别只信 pipdeptree 的“满足”
pipdeptree 说所有依赖都满足 python_version，不代表运行时不崩。3.11 的 AST 优化和异常处理变更会让某些动态代码在首次 import 时就挂掉。
- 加
-X importtime看加载卡在哪：python -X importtime -c "import mymodule" 2> import.log，然后cat import.log | grep -E "(mymodule|error)" - 对核心函数做微基准：
python -m pyperf timeit -s "import json; data=b'{"a":1}'*10000" "json.loads(data)"，对比 3.8 和 3.11 结果；若 3.11 反而慢，说明触发了某处未优化路径 - 如果项目用
eval()或exec()加载字符串代码，3.11 的 AST 缓存机制可能让旧逻辑失效，必须补ast.parse(..., feature_version=(3, 11))
最容易被忽略的是 tomli 和 zoneinfo 这类已内置模块：3.11 里它们从第三方变成标准库，但你的 requirements.txt 若还锁着 tomli==2.0.1，就会和内置版本冲突，导致 ImportError: cannot import name 'TomlDecodeError' from 'tomli' —— 这种问题不会出现在 pipdeptree 里，只能靠运行时暴露。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
