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"。
release 字段就是下载时要对应的构建名。
GitHub 上的发布文件(github.com/wled/WLED/releases)使用同样的名称:
| 构建名 | 典型硬件 | 闪存 | 无线更新 |
|---|---|---|---|
| ESP8266 | D1 mini、NodeMCU | 4 MB | 可以,空间充足 |
| ESP02 | 2 MB 闪存的开发板,许多廉价控制器 | 2 MB | 可以,但很紧 |
| ESP01 | ESP-01、ESP-01S | 1 MB | 不行,构建时未包含 OTA |
| ESP32 | ESP32 开发板、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 0.15 及更早版本上,或者您想自己选文件时:
- 从发布页下载对应您构建版本的文件。
- 进入 Config > Security & Updates,点 Manual OTA Update(WLED 16 上是 Update WLED),或者打开
http://<light-ip>/update。 - 选择文件,点 Update!(WLED 16 上是 Upload)。
- 等待。它会上传、写入并重启,通常不到一分钟。期间不要动电源。
做这些之前,先保存一份备份。Security & Updates 有 Backup presets 和 Backup configuration 按钮。正常更新会保留您的设置,但备份只要十秒钟。备份和恢复 WLED 配置解释了每个文件里有什么。

故障排除: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 扇区,所以更紧。
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。

其他症状
卡在 0%,或者超时。 灯那边的 Wi-Fi 信号弱。把手机拿到离路由器(是路由器,不是灯)更近的地方,或者用有线连接的电脑更新。
重启后回到了旧版本。 上传完成了,但镜像没有通过验证。试试 .bin.gz 或两步法。
更新后回到了 WLED-AP 模式。 少见,但配置丢失时会发生。加入 WLED-AP(密码 wled1234),重新设置 Wi-Fi,然后恢复您的备份。
WLED 16 上效果看起来不一样了。 一些效果 ID 变了(比如效果 77)。WLED Max 会标出使用效果 77 的预设,让您知道哪些需要重新保存。
在手机上更新
在 WLED Max 中,长按设备列表中的灯并选择 固件,或者从 有可用的固件更新 横幅打开 固件更新。Android 在“设备设置”里也有它。
- App 列出官方 WLED GitHub 代码仓库的近期发布版本,包括预发布版。没有稳定版/测试版的切换器,所以点之前先看版本号。
- 它选取您的灯所报告的精确构建版本(ESP32、ESP8266、ESP02、ESP01、S2、S3 或 C3)。如果那个精确文件缺失,它会退回到按芯片类型选择,而 浏览所有版本 让您自己挑。
- 在 可用版本 下点发布版本旁的 下载,然后在 已缓存的固件 下点它旁边的 安装。下载内容会一直缓存,所以之前获取的固件之后不用联网也能安装。

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,而不是中途失败。

更新被拒绝时,界面会建议解决办法,例如清除 OTA 密码或允许来自另一个子网的更新。如果灯运行的是自定义构建,更新横幅会警告安装官方发布版本会用标准固件替换自定义固件和额外的用户模块。App 不能上传您自己的 .bin。自定义构建请用网页界面。
想在您的灯有新的稳定版发布时收到通知,请在 设置›App 偏好设置›通知(Android 上是“应用偏好设置”)中打开 固件更新。它默认是关闭的。
相关内容:WLED 设置详解和WLED 灯为什么总是离线。