WLED 固件 OTA ESP8266 ESP32 WLED Max 操作指南

ESP8266 和 ESP02 上的 WLED OTA 更新:您需要哪个 .bin,以及为什么会失败

为 ESP8266、ESP02 或 ESP01 选对 WLED .bin,了解 2 MB 开发板为什么会空间不足,以及 OTA 失败时怎么用两步更新。

作者: 发布于 更新于

**快速回答:**使用名称与您的灯所报告的构建版本相符的发布文件(WLED Info 页面上的“release”,例如 ESP8266、ESP02 或 ESP32)。在 ESP8266 上,新镜像必须塞进正在运行的固件和文件系统之间的空隙,所以 2 MB 开发板(ESP02 构建)经常以“not enough space”失败。改用压缩的 .bin.gz,或者分两步更新:先装小的 _min 构建,再装完整版。1 MB 开发板(ESP01 构建)完全没有无线更新。它们需要 USB 线和 install.wled.me。

您的灯运行的是哪个构建版本?

在浏览器中打开灯,点 Info(“i”按钮)。版本号和构建名就在那里。或者打开 http://<light-ip>/json/info,找到 "release",例如 "release":"ESP02" 或 "release":"ESP32"。

/json/info(部分)
"ver""0.15.1"
"release""ESP02"
"arch""esp8266"

release 字段就是下载时要对应的构建名。

GitHub 上的发布文件(github.com/wled/WLED/releases)使用同样的名称:

构建名典型硬件闪存无线更新
ESP8266D1 mini、NodeMCU4 MB可以,空间充足
ESP022 MB 闪存的开发板,许多廉价控制器2 MB可以,但很紧
ESP01ESP-01、ESP-01S1 MB不行,构建时未包含 OTA
ESP32ESP32 开发板、QuinLED、大多数控制器4 MB可以
ESP32-S2、S3、C3较新的 ESP32 芯片不定可以

请留在您现在的构建名上。通过无线切换构建版本可能让您得到错误的引脚默认值,或者一盏无法启动的灯。

在网页界面中更新

WLED 16 替您做了大部分工作。进入 Config›Security & Updates,点 Update WLED(或者打开 http://<light-ip>/update)。页面显示已安装的版本、您的 release 名称和最新版本。Auto update 会从 GitHub 获取匹配的文件并上传。在 ESP32 和 4 MB 的 ESP8266 开发板上,这就是全部。在 2 MB 开发板上,请先读下一节,因为 Auto update 选的是普通的 .bin。

WLED 网页界面
WLED Security and Updates 的 Software Update 部分:Update WLED 按钮,以及已勾选的 Only allow update from same network/WiFi 选项和它的 VLAN 警告
Security & Updates,Software Update 部分。
WLED 网页界面
WLED Software Update 页面:已安装版本 WLED 16.0.1,release ESP32,最新版本 v16.0.1,Auto update 按钮,带 Choose File、Ignore firmware validation 和 Upload 的 Manual upload,以及 Revert update
WLED 16.0.1 上的更新页面(一盏 ESP32 灯)。

在 WLED 0.15 及更早版本上,或者您想自己选文件时:

  1. 从发布页下载对应您构建版本的文件。
  2. 进入 Config > Security & Updates,点 Manual OTA Update(WLED 16 上是 Update WLED),或者打开 http://<light-ip>/update。
  3. 选择文件,点 Update!(WLED 16 上是 Upload)。
  4. 等待。它会上传、写入并重启,通常不到一分钟。期间不要动电源。

做这些之前,先保存一份备份。Security & Updates 有 Backup presets 和 Backup configuration 按钮。正常更新会保留您的设置,但备份只要十秒钟。备份和恢复 WLED 配置解释了每个文件里有什么。

WLED 网页界面
WLED Backup and Restore 部分:警告文字、Backup presets 按钮、带 Choose File 和 Upload 的 Restore presets、Backup configuration 按钮、带 Choose File 和 Upload 的 Restore configuration
备份按钮在同一个 Security & Updates 页面的更下方。

故障排除:ESP8266 更新为什么会失败

更新失败:2 MB 开发板上的“Not enough space”

ESP8266 没有 ESP32 那样固定的更新分区。新镜像被暂存在正在运行的固件末尾与文件系统起点之间的空隙里。在 2 MB 开发板上,文件系统从 1,572,864 字节(0x180000)开始。当前固件约 800 KB,留给新镜像的大约是 750 KB,而完整的 WLED 构建比这更大。到 0.15.1 为止的 WLED 还会额外预留一个 4 KB 扇区,所以更紧。

01.5 MB2 MB

2 MB 开发板为什么会空间不足:新镜像必须塞进那个空隙。

两种解决办法:

  • .bin.gz 文件。 ESP8266 可以直接接受 gzip 压缩的镜像,并在启动时解压。它大约小四分之一,这往往就是装得下和装不下的区别。
  • 分两步。 先安装小的 ESP02_min 构建(功能较少,容易装下),重启,然后安装完整的 ESP02 构建。小构建运行时空间更多,所以完整版能装下。ESP02_min 文件从 WLED 16 起才有。0.15 的发布版本没有。

WLED 16 会检查上传文件的构建名是否与运行中的构建匹配,所以从 ESP02 换到 ESP02_min 需要在更新页面勾选 Ignore firmware validation。这是一个已知的上游问题(wled/WLED#5576)。手动路线是 ESP02,然后 ESP02_min.bin.gz,然后 ESP02.bin.gz。

在 ESP01 上立刻失败

ESP01 构建编译时没有包含 OTA。没有可以上传的地方。用 USB 连接开发板,使用 install.wled.me(方法)。

文件选错了

把 ESP32 的 .bin 刷到 ESP8266 上,或者反过来,运气好的话会被拒绝。运气不好的话,灯在您用 USB 重刷之前都无法启动。每次都要对上构建名。

更新失败并出现 401 “Access Denied”

401 表示灯在读取上传内容之前就拒绝了它。消息的第二行说明了原因:

消息原因解决
Please unlock OTA in security settings!勾选了 Lock wireless (OTA) software update在 Security & Updates 中取消勾选(需要 OTA 密码)
Please unlock settings using PIN code!设置页面设了 PIN 码,而这个浏览器还没输入输入 PIN 码,然后重新上传
Client is not on local subnet.仅 WLED 16:上传来自另一个子网,而 Only allow update from same network/WiFi 已勾选,或者来自私有地址范围之外的地址从灯所在网络上的设备更新,取消勾选该选项,或者给设置页面设一个 PIN 码

App 和 Home Assistant 更新灯时会收到同样的回应。Home Assistant 2026.10 及更新版本会显示原因;旧版本则静默失败(见 WLED 与 Home Assistant 问题修复)。

已锁定,或者在另一个子网

在 Security & Updates 中勾选了 Lock wireless (OTA) software update 后,灯会拒绝上传,直到您取消勾选,而这需要 OTA 密码。勾选了 Only allow update from same network/WiFi 后,它会拒绝来自其他子网的更新。如果您的手机在另一个 VLAN 上,请取消勾选它(或者像页面建议的那样设置 PIN 码),或者从灯所在网络上的设备更新。

在 WLED Max 中,这两个开关是“设备设置”的“安全与更新”下的 锁定 OTA 更新 和 仅允许同一子网内的 OTA。

iOS
WLED Max 的“安全与更新”界面:“锁定 OTA 更新”关,“锁定 Wi-Fi 设置”关,“启用 ArduinoOTA”开,“仅允许同一子网内的 OTA”开,已设置 OTA 密码(7 个字符)
WLED Max 中的这两项设置。

其他症状

卡在 0%,或者超时。 灯那边的 Wi-Fi 信号弱。把手机拿到离路由器(是路由器,不是灯)更近的地方,或者用有线连接的电脑更新。

重启后回到了旧版本。 上传完成了,但镜像没有通过验证。试试 .bin.gz 或两步法。

更新后回到了 WLED-AP 模式。 少见,但配置丢失时会发生。加入 WLED-AP(密码 wled1234),重新设置 Wi-Fi,然后恢复您的备份。

WLED 16 上效果看起来不一样了。 一些效果 ID 变了(比如效果 77)。WLED Max 会标出使用效果 77 的预设,让您知道哪些需要重新保存。

在手机上更新

在 WLED Max 中,长按设备列表中的灯并选择 固件,或者从 有可用的固件更新 横幅打开 固件更新。Android 在“设备设置”里也有它。

  1. App 列出官方 WLED GitHub 代码仓库的近期发布版本,包括预发布版。没有稳定版/测试版的切换器,所以点之前先看版本号。
  2. 它选取您的灯所报告的精确构建版本(ESP32、ESP8266、ESP02、ESP01、S2、S3 或 C3)。如果那个精确文件缺失,它会退回到按芯片类型选择,而 浏览所有版本 让您自己挑。
  3. 在 可用版本 下点发布版本旁的 下载,然后在 已缓存的固件 下点它旁边的 安装。下载内容会一直缓存,所以之前获取的固件之后不用联网也能安装。
iOS
WLED Max 的“设备”标签页,Garage Strip 标有“更新”,以及一条“有可用的固件更新”横幅:Garage Strip 可更新到 v16.0.1,带“不再提醒”和“更新”按钮
设备列表中的横幅。

1.1.4 版在 iOS 和 Android 上都替您处理了上面那些 ESP8266 的情况:

  • 在您的开发板上需要两步的发布版本会在列表中标明(“需要分两步更新。‘下载’会获取两个文件。”)。
  • 当完整构建装不下时,App 会提供 开始两步更新。它先安装小版本(“第 1 步,共 2 步:精简版”),再安装完整版(“第 2 步,共 2 步:完整版”),不需要手动下载。如果第 1 步没完成,灯仍在旧固件上,什么都没变。如果第 2 步没完成,灯在小版本上继续工作,重试第 2 步 会把剩下的做完。
  • 如果某个发布版本即使分两步也对那块开发板太大,该行会显示“太大,无法通过 Wi-Fi 安装到这盏灯上”,不会上传任何东西,App 会建议用 install.wled.me 通过 USB 安装。
  • 在没有无线更新的构建(ESP01)上,App 会直接说明并指引您去 install.wled.me,而不是中途失败。
iOS
一盏 ESP02 灯的“固件更新”列表:“可用版本”下有一个标为“太大,无法通过 Wi-Fi 安装到这盏灯上”的每夜版,然后是 v16.0.1 和 v16.0.0,各标有需要分两步更新、“下载”会同时获取两个文件的提示,然后是 v16.0.0-beta 和 v0.15.4,各带一个“下载”按钮
“固件更新”列表中的一盏 ESP02 灯。Android 显示同样的提示。

更新被拒绝时,界面会建议解决办法,例如清除 OTA 密码或允许来自另一个子网的更新。如果灯运行的是自定义构建,更新横幅会警告安装官方发布版本会用标准固件替换自定义固件和额外的用户模块。App 不能上传您自己的 .bin。自定义构建请用网页界面。

想在您的灯有新的稳定版发布时收到通知,请在 设置›App 偏好设置›通知(Android 上是“应用偏好设置”)中打开 固件更新。它默认是关闭的。

相关内容:WLED 设置详解和WLED 灯为什么总是离线。