离线安装ESP-IDF v4.4.1报Python错误、工具下载失败求助

首先明确基础认知：你下载的750MB带.git目录的源码包仅包含IDF核心源码与所有git子模块，工具链、Python依赖属于跨架构、跨平台的独立资源，官方不会将所有平台的二进制资源打包进源码压缩包，因此直接运行./install.sh触发联网下载是正常逻辑，并非压缩包损坏。
以下是经过验证的零联网部署流程，不需要手动修改系统Python软链接、不需要手动凑依赖：

前置准备（需一台和目标无网设备CPU架构一致、Debian大版本一致的有网设备） #

• 将你下载的esp-idf-v4.4.1.zip拷贝到有网设备，解压到固定路径，例如~/esp/esp-idf-v4.4.1
• 提前配置和目标机一致的工具链存储路径环境变量，执行以下命令完成全量依赖下载与环境初始化：

  export IDF_TOOLS_PATH=~/esp/.espressif
  cd ~/esp/esp-idf-v4.4.1
  ./install.sh esp32
  

  该命令执行完成后，会自动在IDF_TOOLS_PATH目录下下载好所有需要的xtensa-esp32-elf、xtensa-esp32s2-elf、riscv32-esp-elf、openocd-esp32等工具链，同时自动创建隔离的Python虚拟环境，安装完全匹配v4.4.1版本要求的所有Python依赖，不会污染系统全局Python环境。
• 打包全量离线资源，执行命令：

  cd ~/esp
  tar zcf esp-idf-v4.4.1-offline-bundle.tar.gz esp-idf-v4.4.1 .espressif
  

  生成的压缩包就是完整可离线部署的安装包，包含所有源码、工具链、Python依赖，无遗漏。

无网目标机部署步骤 #

• 将上一步生成的esp-idf-v4.4.1-offline-bundle.tar.gz拷贝到无网设备，解压到和有网设备完全一致的路径下（例如同样解压到~/esp/目录，保持esp-idf-v4.4.1和.espressif的相对、绝对路径和有网设备一致，避免脚本内硬编码路径识别失败）
• 配置永久环境变量，根据你使用的shell编辑对应配置文件（bash编辑~/.bashrc，zsh编辑~/.zshrc），在文件末尾添加以下两行：

  export IDF_TOOLS_PATH="$HOME/esp/.espressif"
  source $HOME/esp/esp-idf-v4.4.1/export.sh
  

• 执行source ~/.bashrc（对应zsh执行source ~/.zshrc）让环境变量立即生效，不要手动给工具链加PATH、不要手动修改系统python命令软链接，export.sh会自动加载隔离虚拟环境、配置所有工具路径。

有效性验证 #

进入IDF自带的hello_world示例目录，直接执行idf.py set-target esp32，如果正常进入配置流程无依赖报错，即部署完成。

备选方案（不想用整包拷贝时使用） #

如果无法找到同架构有网设备整包拷贝，可以按以下步骤手动凑齐离线资源：

• 对照ESP-IDF v4.4.1的工具版本清单，下载对应Linux架构的所有工具链压缩包，统一放到无网设备$IDF_TOOLS_PATH/dist目录下，再执行./install.sh esp32，脚本会自动识别本地dist目录内的资源，不会触发联网下载。
• Python依赖部分，在有网设备上执行pip download -r <IDF源码路径>/requirements.txt -d python_deps，将所有依赖的wheel包下载到python_deps目录，拷贝到无网设备后，激活IDF自动创建的Python虚拟环境，执行pip install --no-index --find-links=./python_deps -r requirements.txt完成离线安装。

注意：不要直接用Debian系统源安装Python依赖，系统源提供的依赖版本大多和v4.4.1要求的固定版本不匹配，会出现各类运行时兼容性问题。

内容的提问来源于stack exchange，提问作者Boann