xiaozhi-esp32 如何从 ESP-IDF 5.x 迁移到 6.x 编译固件【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32如果你之前用 ESP-IDF 5.x 编译过 xiaozhi-esp32现在拉取当前代码后需要升级 SDK项目已不再支持 ESP-IDF 5.xREADME_zh.md 与 AGENTS.md 都明确写着最低要求为 ESP-IDF v6.0.1推荐使用 ESP-IDF v6.1。组件清单 main/idf_component.yml 也通过idf: version: 6.0.1声明了这一硬性约束用 5.x 会在组件解析阶段直接被拒。本文给出从 5.x 环境切换到 6.x 后重新编译固件的完整路径以及编译成功的判断依据。确认 SDK 版本要求与例外切换前先明确三件事它们都写在项目文档里最低要求 ESP-IDF v6.0.1推荐 ESP-IDF v6.1README_zh.md「开发环境」一节AGENTS.md 同样表述不再支持 ESP-IDF 5.x——不存在兼容降级选项只能把本地 SDK 升到 6.xESP32-S31 板卡如 esp32-s31-korvo-1要求 IDF 6.1 或以上其config.json中该变体带有idf_version: 6.1规则AGENTS.md 中的 CI 矩阵 .github/workflows/build.yml 也专门为这两个 S31 变体使用espressif/idf:v6.1镜像编译而其余变体使用espressif/idf:v6.0.2。个别变体的idf_version规则会按当前 SDK 版本自动过滤。例如 m5stack/corep4 的 config.json 同时声明了6.0与6.0两组构建变体在 6.x 下只有满足规则的变体会进入构建矩阵如果某个 5.x 时代常用的变体在新 SDK 下不再出现先用下文--list-boards确认它是否仍被列出再判断是版本规则过滤还是变体已改名。升级 ESP-IDF 到 6.x 并激活环境按 AGENTS.md「Commands」一节的流程操作安装或选择 ESP-IDF v6.0.1 及以上推荐 v6.1的 SDK 后先激活目标版本的环境再验证版本source /path/to/esp-idf/export.sh idf.py --version/path/to/esp-idf替换为你本机 ESP-IDF 安装目录。idf.py --version输出应显示 6.0.x 或 6.1.x若仍显示 5.x说明激活的是旧 SDK 环境export.sh指向的路径要改。这一步是后续所有构建命令的前提scripts/build.py 依赖IDF_PATH或idf.py来探测当前 SDK 版本版本探测失败时会直接报ESP-IDF version was not detected. Source export.sh before running build.py.退出。列出可用板卡与变体确认 SDK 版本后在项目根目录运行python3 scripts/build.py --list-boardsscripts/build.py 会根据当前激活的 IDF 版本筛选各板卡config.json中带idf_version规则的构建变体输出的是当前 6.x 环境下实际可编译的 board 目录名与变体名。加--json可查看完整机器可读列表CI 的 build.yml 就是这样枚举全量矩阵的。对比 5.x 时代记录下来的板卡清单若某个变体消失了优先怀疑它携带了6.0之类的版本规则若变体仍在但名称变化以--list-boards的最新输出为准。编译固件并判断成功选定板卡后执行标准构建命令python3 scripts/build.py board-directory --name variant-nameboard-directory是main/boards下的相对路径variant-name是config.json中builds[].name的值两者均从--list-boards输出中获取。例如python3 scripts/build.py xmini/c3 --name xmini-c3构建脚本会把目标芯片、生成的 sdkconfig 默认值与板卡名在一次idf.py reconfigure调用中配置完成Component Manager 也会在这一步解析并填充managed_componentsdocker/firmware-builder/README.md 对这一流程有说明。因此首次在新环境下构建需要网络访问否则组件下载会失败。构建成功时产物为build/merged-binary.binCI 正是以该文件的存在作为构建完成的标志build.yml 上传 artifact 时配置了if-no-files-found: error。两点注意事项scripts/build.py 会改动本地sdkconfig与构建状态切换板卡或芯片后不要假设旧的build目录仍代表上一次的目标AGENTS.md 原文提醒。AGENTS.md 明确编译成功不等于硬件验证成功产出 bin 只说明编译通过上机行为仍需实物冒烟测试。如果要在不依赖板卡选择的情况下验证本机 6.x 环境下的构建工具链是否完好可以运行主机侧测试python3 -m unittest discover -s scripts/tests -v这是 CI 每个构建任务开始前执行的第一步build.yml「Test build tooling」全部通过说明scripts/工具链在 6.x 环境下可用。可选分支用 Docker 镜像编译如果不想在本地维护 6.x 工具链仓库自带固件构建容器。按 docker/firmware-builder/README.mddocker build \ --platform linux/arm64 \ --build-arg FIRMWARE_SOURCE_REVISION$(git rev-parse HEAD) \ -f docker/firmware-builder/Dockerfile \ -t xiaozhi/firmware-builder:idf61-arm64 .基础镜像默认是espressif/idf:release-v6.1Dockerfile 中ARG IDF_IMAGEespressif/idf:release-v6.1。然后每次运行只构建一个板卡配置docker run --rm --platform linux/arm64 \ -e FIRMWARE_BOARD_DIRxmini/c3 \ -e FIRMWARE_BOARD_NAMExmini-c3 \ -e FIRMWARE_LANGUAGEzh-CN \ -e FIRMWARE_WAKE_WORDnihaoxiaozhi \ -v $PWD/output:/output \ xiaozhi/firmware-builder:idf61-arm64FIRMWARE_BOARD_DIR、FIRMWARE_BOARD_NAME的取值规则与scripts/build.py一致构建器会先对照源码校验这两个字段。成功任务在挂载的 output 目录写入xiaozhi.bin、merged-binary.bin、build.log和带 SHA-256 校验和的manifest.json。该分支适合 CI 或无头构建本地一次性编译用前文的scripts/build.py路径更直接。小结迁移完成的判定从 5.x 迁移到 6.x 的判定标准是idf.py --version显示 6.0.x 及以上S31 板卡需 6.1python3 scripts/build.py board-directory --name variant-name能产出build/merged-binary.bin主机侧python3 -m unittest discover -s scripts/tests -v全部通过。仓库中不存在针对 5.x 的兼容开关或降级路径5.x 环境只能整体替换为 6.x 后再按本文流程重新配置与编译。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
xiaozhi-esp32 如何从 ESP-IDF 5.x 迁移到 6.x 编译固件【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32如果你之前用 ESP-IDF 5.x 编译过 xiaozhi-esp32现在拉取当前代码后需要升级 SDK项目已不再支持 ESP-IDF 5.xREADME_zh.md 与 AGENTS.md 都明确写着最低要求为 ESP-IDF v6.0.1推荐使用 ESP-IDF v6.1。组件清单 main/idf_component.yml 也通过idf: version: 6.0.1声明了这一硬性约束用 5.x 会在组件解析阶段直接被拒。本文给出从 5.x 环境切换到 6.x 后重新编译固件的完整路径以及编译成功的判断依据。确认 SDK 版本要求与例外切换前先明确三件事它们都写在项目文档里最低要求 ESP-IDF v6.0.1推荐 ESP-IDF v6.1README_zh.md「开发环境」一节AGENTS.md 同样表述不再支持 ESP-IDF 5.x——不存在兼容降级选项只能把本地 SDK 升到 6.xESP32-S31 板卡如 esp32-s31-korvo-1要求 IDF 6.1 或以上其config.json中该变体带有idf_version: 6.1规则AGENTS.md 中的 CI 矩阵 .github/workflows/build.yml 也专门为这两个 S31 变体使用espressif/idf:v6.1镜像编译而其余变体使用espressif/idf:v6.0.2。个别变体的idf_version规则会按当前 SDK 版本自动过滤。例如 m5stack/corep4 的 config.json 同时声明了6.0与6.0两组构建变体在 6.x 下只有满足规则的变体会进入构建矩阵如果某个 5.x 时代常用的变体在新 SDK 下不再出现先用下文--list-boards确认它是否仍被列出再判断是版本规则过滤还是变体已改名。升级 ESP-IDF 到 6.x 并激活环境按 AGENTS.md「Commands」一节的流程操作安装或选择 ESP-IDF v6.0.1 及以上推荐 v6.1的 SDK 后先激活目标版本的环境再验证版本source /path/to/esp-idf/export.sh idf.py --version/path/to/esp-idf替换为你本机 ESP-IDF 安装目录。idf.py --version输出应显示 6.0.x 或 6.1.x若仍显示 5.x说明激活的是旧 SDK 环境export.sh指向的路径要改。这一步是后续所有构建命令的前提scripts/build.py 依赖IDF_PATH或idf.py来探测当前 SDK 版本版本探测失败时会直接报ESP-IDF version was not detected. Source export.sh before running build.py.退出。列出可用板卡与变体确认 SDK 版本后在项目根目录运行python3 scripts/build.py --list-boardsscripts/build.py 会根据当前激活的 IDF 版本筛选各板卡config.json中带idf_version规则的构建变体输出的是当前 6.x 环境下实际可编译的 board 目录名与变体名。加--json可查看完整机器可读列表CI 的 build.yml 就是这样枚举全量矩阵的。对比 5.x 时代记录下来的板卡清单若某个变体消失了优先怀疑它携带了6.0之类的版本规则若变体仍在但名称变化以--list-boards的最新输出为准。编译固件并判断成功选定板卡后执行标准构建命令python3 scripts/build.py board-directory --name variant-nameboard-directory是main/boards下的相对路径variant-name是config.json中builds[].name的值两者均从--list-boards输出中获取。例如python3 scripts/build.py xmini/c3 --name xmini-c3构建脚本会把目标芯片、生成的 sdkconfig 默认值与板卡名在一次idf.py reconfigure调用中配置完成Component Manager 也会在这一步解析并填充managed_componentsdocker/firmware-builder/README.md 对这一流程有说明。因此首次在新环境下构建需要网络访问否则组件下载会失败。构建成功时产物为build/merged-binary.binCI 正是以该文件的存在作为构建完成的标志build.yml 上传 artifact 时配置了if-no-files-found: error。两点注意事项scripts/build.py 会改动本地sdkconfig与构建状态切换板卡或芯片后不要假设旧的build目录仍代表上一次的目标AGENTS.md 原文提醒。AGENTS.md 明确编译成功不等于硬件验证成功产出 bin 只说明编译通过上机行为仍需实物冒烟测试。如果要在不依赖板卡选择的情况下验证本机 6.x 环境下的构建工具链是否完好可以运行主机侧测试python3 -m unittest discover -s scripts/tests -v这是 CI 每个构建任务开始前执行的第一步build.yml「Test build tooling」全部通过说明scripts/工具链在 6.x 环境下可用。可选分支用 Docker 镜像编译如果不想在本地维护 6.x 工具链仓库自带固件构建容器。按 docker/firmware-builder/README.mddocker build \ --platform linux/arm64 \ --build-arg FIRMWARE_SOURCE_REVISION$(git rev-parse HEAD) \ -f docker/firmware-builder/Dockerfile \ -t xiaozhi/firmware-builder:idf61-arm64 .基础镜像默认是espressif/idf:release-v6.1Dockerfile 中ARG IDF_IMAGEespressif/idf:release-v6.1。然后每次运行只构建一个板卡配置docker run --rm --platform linux/arm64 \ -e FIRMWARE_BOARD_DIRxmini/c3 \ -e FIRMWARE_BOARD_NAMExmini-c3 \ -e FIRMWARE_LANGUAGEzh-CN \ -e FIRMWARE_WAKE_WORDnihaoxiaozhi \ -v $PWD/output:/output \ xiaozhi/firmware-builder:idf61-arm64FIRMWARE_BOARD_DIR、FIRMWARE_BOARD_NAME的取值规则与scripts/build.py一致构建器会先对照源码校验这两个字段。成功任务在挂载的 output 目录写入xiaozhi.bin、merged-binary.bin、build.log和带 SHA-256 校验和的manifest.json。该分支适合 CI 或无头构建本地一次性编译用前文的scripts/build.py路径更直接。小结迁移完成的判定从 5.x 迁移到 6.x 的判定标准是idf.py --version显示 6.0.x 及以上S31 板卡需 6.1python3 scripts/build.py board-directory --name variant-name能产出build/merged-binary.bin主机侧python3 -m unittest discover -s scripts/tests -v全部通过。仓库中不存在针对 5.x 的兼容开关或降级路径5.x 环境只能整体替换为 6.x 后再按本文流程重新配置与编译。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
