1. 为什么需要从GitHub迁移到Gitee作为一个长期使用乐鑫开发工具链的开发者我深刻体会到从GitHub克隆代码库的痛苦。每次执行git clone --recursive https://github.com/espressif/esp-idf.git时看着那几KB/s的下载速度我都忍不住想砸键盘。特别是在早上高峰期下载经常中断又要从头开始这种体验简直让人崩溃。乐鑫的开发工具链包含大量子模块这使得完整克隆一个项目变得异常耗时。我曾经做过测试在没有任何加速手段的情况下完整克隆esp-idf可能需要数小时甚至一整天时间。这对于需要频繁搭建开发环境或者切换项目分支的开发者来说简直是噩梦。国内开发者面临的主要问题包括GitHub服务器位于国外网络延迟高跨国带宽有限特别是在高峰时段大文件传输容易中断且不支持断点续传子模块嵌套下载会放大上述所有问题Gitee作为国内知名的代码托管平台提供了乐鑫官方维护的镜像仓库。通过将GitHub仓库镜像到国内服务器下载速度可以从几KB/s提升到几MB/s效率提升数十倍不止。我在实际项目中测试完整克隆esp-idf及其所有子模块从原来的3-4小时缩短到5-10分钟这种体验差异就像从自行车换成了高铁。2. 准备工作Gitee账号与SSH配置2.1 注册Gitee账号首先你需要一个Gitee账号。访问Gitee官网点击注册按钮按照提示填写用户名、密码和邮箱。这里有个小建议最好使用你常用的邮箱注册因为后续的SSH密钥和项目通知都会发送到这个邮箱。注册完成后记得验证邮箱。很多开发者跳过这一步结果后面配置SSH时遇到各种权限问题。我就曾经因为没验证邮箱调试了半天SSH连接问题最后发现是账号状态不完整导致的。2.2 配置Git环境在开始克隆仓库前我们需要先配置本地的Git环境。打开终端Windows用户可以使用Git Bash或者WSL执行以下命令设置全局用户名和邮箱git config --global user.name 你的Gitee用户名 git config --global user.email 你的Gitee注册邮箱这两个信息非常重要必须与Gitee账号信息一致。我曾经遇到过因为邮箱不一致导致代码提交不被计入贡献统计的情况。检查配置是否正确可以使用git config --global --list2.3 生成并配置SSH密钥SSH密钥是安全连接Gitee的基础。生成密钥对只需要一行命令ssh-keygen -C 你的邮箱 -t rsa执行后会提示你输入保存位置和密码直接按回车使用默认值即可。生成的密钥默认保存在~/.ssh/目录下其中id_rsa是私钥id_rsa.pub是公钥。接下来把公钥添加到Gitee。用文本编辑器打开id_rsa.pub文件复制全部内容。登录Gitee进入设置-SSH公钥粘贴公钥内容并保存。测试SSH连接是否成功ssh -T gitgitee.com如果看到Welcome to Gitee, YourName!的欢迎信息说明配置成功。我第一次配置时遇到了权限问题后来发现是.ssh目录权限设置不对用chmod 700 ~/.ssh修复了。3. 克隆乐鑫官方仓库3.1 识别官方镜像仓库乐鑫在Gitee上维护了官方镜像地址是https://gitee.com/EspressifSystems。一定要认准这个官方组织因为Gitee上可能存在其他非官方镜像这些镜像可能更新不及时或者缺少某些组件。官方仓库与GitHub上的原始仓库保持同步更新你可以放心使用。我曾经尝试过非官方镜像结果发现缺少某些子模块导致编译失败浪费了不少时间。3.2 基础仓库克隆克隆主仓库非常简单以esp-idf为例git clone https://gitee.com/EspressifSystems/esp-idf.git注意这里我们没有使用--recursive参数因为直接克隆所有子模块还是会从GitHub下载速度依然很慢。正确的做法是先克隆主仓库然后再用专门工具处理子模块。克隆完成后记得检查版本。很多项目对esp-idf版本有特定要求可以使用git checkout切换cd esp-idf git checkout v4.44. 处理子模块加速4.1 获取esp-gitee-tools工具乐鑫官方提供了一个非常实用的工具esp-gitee-tools专门用于解决子模块下载慢的问题。先克隆这个工具git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git这个工具包含几个实用脚本其中最重要的是submodule-update.sh它能自动将子模块的GitHub地址替换为Gitee镜像地址。4.2 配置环境变量为了方便使用建议设置环境变量指向工具目录cd esp-gitee-tools export EGT_PATH$(pwd)这样之后更新子模块时就不需要输入完整路径了。你可以把这行命令添加到.bashrc或.zshrc中这样每次打开终端都会自动设置。4.3 更新子模块进入esp-idf目录执行子模块更新脚本cd ../esp-idf $EGT_PATH/submodule-update.sh这个脚本会自动完成以下操作遍历所有子模块将GitHub地址替换为对应的Gitee镜像地址初始化并更新子模块我第一次使用时看着子模块以MB/s的速度下载简直感动到想哭。之前需要几小时才能完成的下载现在几分钟就搞定了。5. 常见问题与解决方案5.1 网络中断恢复如果在更新子模块过程中网络中断不要担心你可以直接重新运行submodule-update.sh脚本。这个脚本是幂等的已经成功下载的子模块不会重复下载。我曾经在更新过程中遇到过几次网络波动重新运行脚本后它会从断点继续不会浪费已经下载的内容。5.2 版本切换注意事项当你切换esp-idf版本时特别是大版本切换时建议重新运行子模块更新脚本。因为不同版本可能包含不同的子模块集合直接使用git命令更新可能会遗漏某些子模块。例如从v4.3切换到v5.0时我遇到了编译错误后来发现是因为某些子模块没有正确更新。重新运行submodule-update.sh后问题解决。5.3 日常更新策略日常开发中如果只是常规更新可以使用标准git命令git pull git submodule update --init --recursive但如果你发现速度变慢或者新增了子模块还是建议使用submodule-update.sh脚本。这个脚本会确保所有子模块都从Gitee镜像下载。6. 进阶技巧与优化建议6.1 多项目共享工具链如果你同时开发多个基于乐鑫平台的项目可以考虑将工具链安装在公共位置然后通过环境变量引用。这样可以避免每个项目都重复下载工具链。在~/.bashrc中添加export IDF_PATH~/esp/esp-idf export PATH$IDF_PATH/tools:$PATH然后执行source ~/.bashrc使配置生效。这样所有项目都可以共享同一份工具链既节省空间又便于统一管理。6.2 使用镜像站加速工具下载除了代码仓库乐鑫的工具安装器也可以配置使用国内镜像。编辑$IDF_PATH/tools/idf_tools.py找到DOWNLOAD_URL开头的行修改为DOWNLOAD_URL https://dl.espressif.cn/dl/esp-idf/tools/这样下载工具链时也会从国内服务器获取速度更快。我在配置新开发环境时这个技巧帮我节省了大量时间。6.3 自动化脚本整合为了进一步简化流程我创建了一个自动化脚本包含从克隆到配置的完整步骤#!/bin/bash # 克隆esp-idf git clone https://gitee.com/EspressifSystems/esp-idf.git cd esp-idf git checkout $1 # 使用参数指定版本 # 克隆esp-gitee-tools cd .. git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git export EGT_PATH$(pwd)/esp-gitee-tools # 更新子模块 cd esp-idf $EGT_PATH/submodule-update.sh # 安装工具链 ./install.sh保存为setup_esp.sh后可以通过./setup_esp.sh v4.4一键搭建指定版本的环境。这个脚本在我的团队中广受好评新成员 onboarding 时间从一天缩短到一小时。
乐鑫开发工具链国内镜像加速实战：从GitHub到Gitee的极速迁移
发布时间：2026/7/17 14:09:44
1. 为什么需要从GitHub迁移到Gitee作为一个长期使用乐鑫开发工具链的开发者我深刻体会到从GitHub克隆代码库的痛苦。每次执行git clone --recursive https://github.com/espressif/esp-idf.git时看着那几KB/s的下载速度我都忍不住想砸键盘。特别是在早上高峰期下载经常中断又要从头开始这种体验简直让人崩溃。乐鑫的开发工具链包含大量子模块这使得完整克隆一个项目变得异常耗时。我曾经做过测试在没有任何加速手段的情况下完整克隆esp-idf可能需要数小时甚至一整天时间。这对于需要频繁搭建开发环境或者切换项目分支的开发者来说简直是噩梦。国内开发者面临的主要问题包括GitHub服务器位于国外网络延迟高跨国带宽有限特别是在高峰时段大文件传输容易中断且不支持断点续传子模块嵌套下载会放大上述所有问题Gitee作为国内知名的代码托管平台提供了乐鑫官方维护的镜像仓库。通过将GitHub仓库镜像到国内服务器下载速度可以从几KB/s提升到几MB/s效率提升数十倍不止。我在实际项目中测试完整克隆esp-idf及其所有子模块从原来的3-4小时缩短到5-10分钟这种体验差异就像从自行车换成了高铁。2. 准备工作Gitee账号与SSH配置2.1 注册Gitee账号首先你需要一个Gitee账号。访问Gitee官网点击注册按钮按照提示填写用户名、密码和邮箱。这里有个小建议最好使用你常用的邮箱注册因为后续的SSH密钥和项目通知都会发送到这个邮箱。注册完成后记得验证邮箱。很多开发者跳过这一步结果后面配置SSH时遇到各种权限问题。我就曾经因为没验证邮箱调试了半天SSH连接问题最后发现是账号状态不完整导致的。2.2 配置Git环境在开始克隆仓库前我们需要先配置本地的Git环境。打开终端Windows用户可以使用Git Bash或者WSL执行以下命令设置全局用户名和邮箱git config --global user.name 你的Gitee用户名 git config --global user.email 你的Gitee注册邮箱这两个信息非常重要必须与Gitee账号信息一致。我曾经遇到过因为邮箱不一致导致代码提交不被计入贡献统计的情况。检查配置是否正确可以使用git config --global --list2.3 生成并配置SSH密钥SSH密钥是安全连接Gitee的基础。生成密钥对只需要一行命令ssh-keygen -C 你的邮箱 -t rsa执行后会提示你输入保存位置和密码直接按回车使用默认值即可。生成的密钥默认保存在~/.ssh/目录下其中id_rsa是私钥id_rsa.pub是公钥。接下来把公钥添加到Gitee。用文本编辑器打开id_rsa.pub文件复制全部内容。登录Gitee进入设置-SSH公钥粘贴公钥内容并保存。测试SSH连接是否成功ssh -T gitgitee.com如果看到Welcome to Gitee, YourName!的欢迎信息说明配置成功。我第一次配置时遇到了权限问题后来发现是.ssh目录权限设置不对用chmod 700 ~/.ssh修复了。3. 克隆乐鑫官方仓库3.1 识别官方镜像仓库乐鑫在Gitee上维护了官方镜像地址是https://gitee.com/EspressifSystems。一定要认准这个官方组织因为Gitee上可能存在其他非官方镜像这些镜像可能更新不及时或者缺少某些组件。官方仓库与GitHub上的原始仓库保持同步更新你可以放心使用。我曾经尝试过非官方镜像结果发现缺少某些子模块导致编译失败浪费了不少时间。3.2 基础仓库克隆克隆主仓库非常简单以esp-idf为例git clone https://gitee.com/EspressifSystems/esp-idf.git注意这里我们没有使用--recursive参数因为直接克隆所有子模块还是会从GitHub下载速度依然很慢。正确的做法是先克隆主仓库然后再用专门工具处理子模块。克隆完成后记得检查版本。很多项目对esp-idf版本有特定要求可以使用git checkout切换cd esp-idf git checkout v4.44. 处理子模块加速4.1 获取esp-gitee-tools工具乐鑫官方提供了一个非常实用的工具esp-gitee-tools专门用于解决子模块下载慢的问题。先克隆这个工具git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git这个工具包含几个实用脚本其中最重要的是submodule-update.sh它能自动将子模块的GitHub地址替换为Gitee镜像地址。4.2 配置环境变量为了方便使用建议设置环境变量指向工具目录cd esp-gitee-tools export EGT_PATH$(pwd)这样之后更新子模块时就不需要输入完整路径了。你可以把这行命令添加到.bashrc或.zshrc中这样每次打开终端都会自动设置。4.3 更新子模块进入esp-idf目录执行子模块更新脚本cd ../esp-idf $EGT_PATH/submodule-update.sh这个脚本会自动完成以下操作遍历所有子模块将GitHub地址替换为对应的Gitee镜像地址初始化并更新子模块我第一次使用时看着子模块以MB/s的速度下载简直感动到想哭。之前需要几小时才能完成的下载现在几分钟就搞定了。5. 常见问题与解决方案5.1 网络中断恢复如果在更新子模块过程中网络中断不要担心你可以直接重新运行submodule-update.sh脚本。这个脚本是幂等的已经成功下载的子模块不会重复下载。我曾经在更新过程中遇到过几次网络波动重新运行脚本后它会从断点继续不会浪费已经下载的内容。5.2 版本切换注意事项当你切换esp-idf版本时特别是大版本切换时建议重新运行子模块更新脚本。因为不同版本可能包含不同的子模块集合直接使用git命令更新可能会遗漏某些子模块。例如从v4.3切换到v5.0时我遇到了编译错误后来发现是因为某些子模块没有正确更新。重新运行submodule-update.sh后问题解决。5.3 日常更新策略日常开发中如果只是常规更新可以使用标准git命令git pull git submodule update --init --recursive但如果你发现速度变慢或者新增了子模块还是建议使用submodule-update.sh脚本。这个脚本会确保所有子模块都从Gitee镜像下载。6. 进阶技巧与优化建议6.1 多项目共享工具链如果你同时开发多个基于乐鑫平台的项目可以考虑将工具链安装在公共位置然后通过环境变量引用。这样可以避免每个项目都重复下载工具链。在~/.bashrc中添加export IDF_PATH~/esp/esp-idf export PATH$IDF_PATH/tools:$PATH然后执行source ~/.bashrc使配置生效。这样所有项目都可以共享同一份工具链既节省空间又便于统一管理。6.2 使用镜像站加速工具下载除了代码仓库乐鑫的工具安装器也可以配置使用国内镜像。编辑$IDF_PATH/tools/idf_tools.py找到DOWNLOAD_URL开头的行修改为DOWNLOAD_URL https://dl.espressif.cn/dl/esp-idf/tools/这样下载工具链时也会从国内服务器获取速度更快。我在配置新开发环境时这个技巧帮我节省了大量时间。6.3 自动化脚本整合为了进一步简化流程我创建了一个自动化脚本包含从克隆到配置的完整步骤#!/bin/bash # 克隆esp-idf git clone https://gitee.com/EspressifSystems/esp-idf.git cd esp-idf git checkout $1 # 使用参数指定版本 # 克隆esp-gitee-tools cd .. git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git export EGT_PATH$(pwd)/esp-gitee-tools # 更新子模块 cd esp-idf $EGT_PATH/submodule-update.sh # 安装工具链 ./install.sh保存为setup_esp.sh后可以通过./setup_esp.sh v4.4一键搭建指定版本的环境。这个脚本在我的团队中广受好评新成员 onboarding 时间从一天缩短到一小时。
