怎么在不同平台制作Python运行环境的离线包
部分业务环境网络隔离，无法连通公网PyPI源，不能在线下载Python依赖包。解决方案为：在可联网设备预先制作适配目标服务器的离线依赖包，再将包文件迁移至隔离环境完成本地安装。
开发主机与隔离服务器普遍存在硬件架构、操作系统、GLIBC库、Python版本差异，直接执行原生pip download会下载适配本机环境的Wheel包，迁移离线部署后会触发ABI校验失败、C/C++原生扩展编译失败等问题。可通过参数强制指定目标环境，在本地联网设备生成任意平台可用的Python离线依赖包。
1 底层机制：pip平台标签匹配逻辑
pip download默认读取当前设备架构、ABI、Python版本，自动筛选对应安装包。若联网开发机为x86_64 Windows，下载得到win_amd64格式Wheel文件，无法在Linux aarch64服务器正常安装。
通过指定参数强制覆盖本机环境探测逻辑，可定向拉取适配隔离服务器的二进制包，核心参数作用：
- --platform：指定目标系统架构标签，限定二进制包适配范围
- --python-version：锁定目标Python主版本
- --implementation：指定解释器类型，业务场景统一使用cp（CPython）
- --abi：绑定Python ABI版本，与Python版本强绑定
- --only-binary=:all:：仅下载预编译whl包，过滤源码tar.gz包
grpcio、numpy等包含C/C++扩展的组件，源码包离线安装需要gcc、cmake、系统头文件等编译工具链，隔离服务器一般未预装，该参数可直接规避离线编译失败问题。
整套参数等效模拟目标服务器运行环境，从镜像源筛选匹配的预编译二进制包。
2 示例：麒麟V11 aarch64 环境完整构建
2.1 目标环境
内核架构
Linux host-10-252-3-214 6.6.0-32.7.v2505.ky11.aarch64 #1 SMP PREEMPT_DYNAMIC Fri Jul 4 14:46:19 UTC 2025 aarch64 aarch64 aarch64 GNU/LinuxGLIBC版本
ldd (GNU libc) 2.38Python版本
Python 3.11.6需求：在联网x86开发机下载grpcio-tools全部依赖，输出适配该ARM64服务器的离线二进制包。
3 离线包下载命令说明
单行完整命令通用结构：
pip download [待下载依赖包名] --platform [目标平台标识] --python-version [Python主版本] --implementation cp --abi [对应ABI标识] --only-binary=:all: -d [本地存储文件夹]
命令各字段作用：
- pip download：下载主命令，后方填写1个或多个依赖包，多个包用空格分隔；
- --platform：填写目标服务器硬件架构与系统标准标签；
- --python-version：填写目标环境Python主版本号；
- --implementation cp：固定参数，代表使用CPython解释器；
- --abi：填写对应Python版本匹配的ABI标识；
- --only-binary=:all:：强制仅下载预编译whl二进制包，跳过源码包；
- -d：自定义离线包存放目录。
适配本次麒麟V11 aarch64环境的实际命令：
pip download grpcio-tools --platform manylinux2014_aarch64 --python-version 3.11 --implementation cp --abi cp311 --only-binary=:all: -d ./offline_packages当然你也可以添加下载源，来加快下载速度，就比如清华源
pip download grpcio-tools -i https://pypi.tuna.tsinghua.edu.cn/simple --platform manylinux2014_aarch64 --python-version 3.11 --implementation cp --abi cp311 --only-binary=:all: -d ./offline_packages执行完成后，./offline_packages目录存储全部依赖whl文件，文件名自带aarch64架构标识。
4 参数说明
- grpcio-tools：待下载核心包，支持批量传入多个包名
- --platform manylinux2014_aarch64：ARM64 Linux通用二进制标准，要求GLIBC≥2.17，目标服务器2.38版本满足兼容条件
- --python-version 3.11：限定Python主版本，用于筛选对应ABI包
- --implementation cp：指定CPython解释器
- --abi cp311：ABI标识，与Python版本一一对应，版本不匹配直接安装失败
- --only-binary=:all:：禁用源码包，带有原生扩展的组件必须携带该参数
- -d ./offline_packages：包输出目录，便于打包迁移至隔离网络
5 下载产物校验
执行目录查看命令
ls offline_packages/标准输出示例
grpcio_tools-1.62.1-cp311-cp311-manylinux_2_17_aarch64.whl
grpcio-1.62.1-cp311-cp311-manylinux_2_17_aarch64.whl
protobuf-4.25.3-py3-none-any.whl校验规则：文件名包含cp311、aarch64字段即代表适配目标环境；参数配置错误下载x86_64包时，离线安装会抛出平台不支持异常；纯Python组件生成py3-none-any.whl，全平台通用。
6 服务器离线安装
将完整offline_packages目录传输至隔离服务器，执行安装命令
pip install --no-index --find-links ./offline_packages grpcio-tools参数说明
--no-index：禁用在线PyPI索引，仅使用本地离线文件--find-links：指定本地目录作为依赖检索源- 多Python环境切换为
python3 -m pip install，规避版本冲突
7 多平台适配配置
构建离线包的核心配置项为--platform标签，主流环境适配参数如下：
| 目标运行环境 | --platform 参数 | 适配GLIBC基线 |
|---|---|---|
| x86_64 Linux | manylinux2014_x86_64 | ≥2.17（CentOS7、老国产x86服务器） |
| x86_64 Linux | manylinux_2_28_x86_64 | ≥2.28（新版麒麟、Ubuntu） |
| aarch64 Linux | manylinux2014_aarch64 | ≥2.17（鲲鹏、飞腾老旧机型） |
| aarch64 Linux | manylinux_2_28_aarch64 | ≥2.28（新版ARM服务器） |
| Windows 64位 | win_amd64 | Windows Server |
| Intel Mac | macosx_10_9_x86_64 | Intel工作站 |
| Mac M系列 | macosx_11_0_arm64 | Apple Silicon设备 |
选型规则
- 查看GLIBC版本命令：
ldd --version，低版本系统选用manylinux2014标签 - 无对应预编译whl文件时，改用linux_aarch64通用标签；仍无二进制包则移除
--only-binary，下载源码包，同时在目标服务器预装编译工具链 - 纯Python包可省略平台参数，标准化交付建议统一使用完整参数配置
8 常见故障对应解决办法
故障1：下载提示无匹配发行包
根因：指定平台标签在PyPI不存在对应预编译whl
处理：切换兼容性更广的通用标签；移除--only-binary下载源码包，隔离服务器提前部署gcc、python-dev编译组件
故障2：安装报错wheel平台不支持
根因：whl架构、ABI标签与目标服务器不兼容
定位：目标服务器执行以下命令导出本机支持标签，反向调整下载参数
python3 -c "import pip._internal.utils.compatibility_tags; print(list(pip._internal.utils.compatibility_tags.get_supported()))"故障3：依赖包文件体积过大
优化：添加--no-deps仅下载主包，人工梳理维护依赖树；生产隔离环境建议保留全量依赖，防止部署缺包
故障4：离线服务器未安装pip
处理1：联网环境单独下载pip whl包，离线手动安装
处理2：执行系统初始化工具 python3 -m ensurepip
9 总结
隔离网络下安装Python依赖采用离线包预构建方案。依靠pip多组环境强制参数，可在任意联网主机生成适配x86、ARM、Windows、macOS等各类异构设备的离线包，仅修改platform参数即可适配不同目标环境，覆盖全隔离网络Python部署场景。