在 Ubuntu 环境下使用 PlatformIO 进行 ESP32 开发时，初次搭建环境往往会遇到一个令人头疼的问题：依赖包下载极慢甚至超时失败。

PlatformIO 默认从海外服务器拉取工具链和框架包（尤其是framework-arduinoespressif32这种几百兆的大包），在国内网络环境下极易卡死。本文将分享一个亲测有效的解决方案：通过配置本地proxy加速 PlatformIO 下载，帮你彻底解决环境搭建的网络瓶颈。

一、 问题背景

在执行 PlatformIO 初始化或手动安装依赖时，终端常常卡在Downloading 0%或直接抛出超时错误：

Error: [API] Could not connect to PlatformIO Registry Service. Please try later.

虽然配置国内镜像源（如清华源、阿里源）能缓解部分问题，但有时仍无法完全解决。此时，让 PlatformIO 走代理是最直接有效的“杀手锏”。

二、 解决步骤

1. 确认你的proxy地址

假设你的proxy服务器运行在局域网或本地，地址为xx.xx.xx.xx，端口为8888。

2. 配置环境变量（临时生效）

PlatformIO 底层基于 Python 的requests库进行 HTTP 请求，因此可以通过设置系统环境变量来指定代理。

在 Ubuntu 终端中执行以下命令（注意：环境变量名必须大写）：

export HTTP_PROXY="http://xx.xx.xx.xx:xxxx" export HTTPS_PROXY="http://xx.xx.xx.xx:xxxx" "

3. 验证代理是否生效

使用curl命令测试是否能通过proxy连通 PlatformIO 官方注册中心：

curl -I https://registry.platformio.org

如果返回了HTTP/1.1 200 Connection established和HTTP/2 200状态码，说明代理配置成功！

4. 清理损坏的缓存（关键）

由于之前网络不好，本地可能已经留下了残缺的缓存文件。如果不清理，PlatformIO 可能会尝试复用坏文件导致继续报错。执行以下命令清理缓存：

rm -rf ~/.platformio/.cache

5. 重新执行下载命令

在同一个终端窗口中，重新运行你的安装命令（以安装 ESP32 核心框架为例）：

pio pkg install --global --tool "platformio/framework-arduinoespressif32"

此时你会发现，下载速度有了质的飞跃，几百兆的包很快就能下载完成。

三、 进阶：如何永久生效？

如果你希望以后每次打开终端都自动使用这个proxy，避免重复输入export命令，可以将其写入 Shell 配置文件中

echo 'export HTTP_PROXY="http://10.128.63.63:8888"' >> ~/.bashrc echo 'export HTTPS_PROXY="http://10.128.63.63:8888"' >> ~/.bashrc source ~/.bashrc