离线安装Python依赖需覆盖完整依赖树并补全pip构建链，否则pip install -r会直接报错；pip download -r默认只下业务包，不包含wheel、setuptools等底层工具，且平台与Python版本必须严格匹配，否则无法安装。
离线安装 Python 依赖不是“传几个 .whl 就完事”，关键在于是否覆盖了整棵依赖树，以及是否补全了 pip 自身的构建链。漏掉 wheel 或平台不匹配，pip install -r requirements.txt 会直接报错退出，而不是提示你缺什么。
为什么 pip download -r requirements.txt 还不够？
它默认只下载业务依赖，但不会拉取 pip 构建过程必需的底层工具包，比如 wheel、setuptools（尤其当遇到 .tar.gz 源码包时）。更隐蔽的问题是：如果你在 Windows 上下载，却要装到 CentOS 7 的服务器上，pip download 默认产出的是当前系统平台的包（如 win_amd64），根本没法用。
-
pip download不自动包含wheel包 —— 它被 pip 视为“安装器自身的一部分”，不在依赖树里 - 没加
--only-binary=:all:时，可能混入.tar.gz源码包，离线机若无编译环境（如无 Visual Studio Build Tools 或 gcc），安装直接失败 - 没指定
--platform和--python-version，跨平台下载等于白忙
必须手动补全的三个核心构建包
即使你的 requirements.txt 里一个包都没写，只要离线机上 pip 要装任何带 C 扩展或源码分发的包，这三样就缺一不可：
-
wheel-*.whl：负责把源码构建成.whl，没有它，.tar.gz包无法安装 -
setuptools-*.whl：提供setup.py运行时支持，很多老包仍依赖它 -
pip-*.whl（可选但强推）：新版 pip 对离线模式兼容更好，比如支持--find-links多目录、更准的依赖解析
在联网机执行：pip download wheel setuptools pip --no-deps --only-binary=:all: -d ./packages
立即学习“Python免费学习笔记（深入）”；
pip download 跨平台参数怎么配？
目标机器是啥，你就得按它的实际环境来下包。常见组合（2026 年主流）：
- CentOS 7 / Rocky Linux 8 x86_64 →
--platform manylinux2014_x86_64 - Windows Server 2019 x64 →
--platform win_amd64 - macOS Sonoma Intel →
--platform macosx_10_15_x86_64 - macOS Sequoia Apple Silicon →
--platform macosx_11_0_arm64 - Python 版本必须严格匹配，例如目标机是
Python 3.10.12，就得加--python-version 3.10
完整命令示例：pip download -r requirements.txt --only-binary=:all: --platform manylinux2014_x86_64 --python-version 3.10 -d ./packages
离线机上安装顺序不能乱
先装构建工具，再装业务包。顺序错了，pip 会卡在第一个 .tar.gz 上不动：
- 进入包目录：
cd ./packages - 优先装
wheel：pip install wheel-*.whl - 再装
setuptools和pip（如有）：pip install setuptools-*.whl pip-*.whl - 最后批量装业务依赖：
pip install --no-index --find-links=. -r ../requirements.txt
注意：--find-links=. 中的点必须是当前目录，且所有 .whl 都得在这个目录下——子目录不会被扫描。
最容易被跳过的点：离线安装前，务必确认目标机的 pip list 里没有残留旧版本包；如果有，--force-reinstall 或先 pip uninstall 干净再装。否则依赖版本冲突会导致运行时报 ImportError，而错误信息里完全看不出是离线安装惹的祸。
