pip反复下载同一wheel是因默认不复用已下载文件，其缓存仅作用于http响应而非wheel分发；解决方法是用--find-links指向本地wheel目录并配合--no-index和--no-deps。
pip install 时为什么反复下载同一个 wheel
因为 pip 默认不复用已下载的 wheel 文件，每次安装都会重新获取——哪怕你刚装过一模一样的版本。这不是 bug，是设计如此：pip 的缓存只对 http 响应生效，而 wheel 下载属于「构建后分发」环节，走的是单独的下载逻辑。
常见错误现象：pip install requests 执行两次，网络请求日志里出现两轮 Downloading requests-2.31.0-py3-none-any.whl；本地磁盘没有保留中间产物。
- 触发场景：CI 环境反复重装依赖、离线环境手动传包、多项目共用同一份依赖但没共享缓存
- 根本原因：pip 的
--find-links和--no-index不自动启用本地 wheel 复用，它只管“从哪找”，不管“找过了要不要再找” - 解决方向不是关掉网络，而是让 pip 明确知道“这个 wheel 我已经有，别下了”
怎么让 pip 优先用本地 wheel 缓存
核心是把 wheel 文件放进 pip 能主动扫描的缓存目录，并确保安装命令带上对应标记。pip 自带的 --find-links + --no-deps 组合容易误用，真正稳定的做法是用 --find-links 指向一个本地目录，再加 --trusted-host（如果用 http）和 --no-index 强制禁用 PyPI。
- 步骤一：把 wheel 文件统一丢进某个目录，比如
./wheels/，支持子目录嵌套 - 步骤二：运行
pip install --find-links ./wheels/ --no-index --no-deps requests - 注意：
--no-deps是关键——否则 pip 仍会尝试去 PyPI 拉依赖项；若需递归安装，得保证所有依赖 wheel 都在该目录下 - 路径必须是绝对路径或相对于当前工作目录的相对路径；
~/wheels这种写法在某些 shell 下不展开，建议用$HOME/wheels
cache-dir 和 wheel-dir 的区别与误用风险
--cache-dir 控制的是 pip 内部 HTTP 缓存和构建临时文件位置，不影响 wheel 复用行为；--wheel-dir 是旧版参数，仅用于“把构建出的 wheel 存到哪”，不参与安装时的查找逻辑——这两个都不是你要找的“本地 wheel 缓存开关”。
立即学习“Python免费学习笔记（深入）”；
- 常见坑：
pip install --cache-dir ./pip-cache requests完全无效，cache-dir 不改变 wheel 下载策略 - 另一个坑：
pip wheel --wheel-dir ./wheels requests只生成 wheel，不自动注册为可安装源；必须配合--find-links才能被后续install命令感知 - 兼容性注意：Python 3.12+ 中
--wheel-dir已弃用，改用--wheel标志控制是否生成 wheel，但依然不解决复用问题
CI/CD 中稳定复用 wheel 的最小实践
在 GitHub Actions 或 GitLab CI 里，靠 pip cache 指令本身不能解决 wheel 复用，得把 wheel 构建和安装拆成两步，并显式上传/下载 wheel 包。
- 构建阶段：用
pip wheel --no-deps --wheel-dir ./dist -r requirements.txt生成所有 wheel 到./dist/ - 缓存该目录（GitHub Actions 用
actions/cache，key 包含requirements.txthash） - 安装阶段：用
pip install --find-links ./dist --no-index --no-deps -r requirements.txt - 额外提醒：如果
requirements.txt含git+或path:依赖，它们不会被打包成 wheel，需单独处理或排除
复杂点在于 wheel 名字包含平台标签（如 cp39-cp39-manylinux_2_17_x86_64），跨平台 CI 时得确认构建环境和目标环境 ABI 兼容，否则 pip 会跳过匹配失败的 wheel 并回退到源码安装。
