Web Server OTA 更新

Web Server OTA 平台允许您直接通过 Web 界面将新的固件二进制文件上传到您的 ESPHome 设备。这提供了一种无需命令行工具或 ESPHome 仪表板即可更新设备的用户友好方式。

启用后，设备的 Web 界面上将出现一个”OTA Update”部分，您可以在其中选择并上传固件文件。这对于已部署在野外的设备或希望让非技术用户执行更新的情况特别有用。

WARNING

在无认证的情况下通过 Web 界面启用 OTA 更新，任何具有您设备网络访问权限的人都可以上传新的固件。在使用此功能时，强烈建议在 Web 服务器上启用认证。

# 示例配置条目
web_server:
  port: 80
  auth:
    username: !secret web_server_username
    password: !secret web_server_password

ota:
  - platform: web_server

配置变量

id (可选, ID): 手动指定用于代码生成的 ID。
由 Ota 支持的所有自动化。

NOTE

此平台要求配置中已配置 Web Server 组件。

从旧版配置迁移

在 ESPHome 2025.7.0 之前，OTA 功能内置于 web_server 组件中，使用 ota 选项。现已移至独立的平台，以保持与其他 OTA 方式的一致性。

旧配置：

web_server:
  port: 80
  ota: true  # 或 ota: false 以禁用

新配置：

web_server:
  port: 80

ota:
  - platform: web_server  # 添加此处以启用 Web OTA

如果您之前在 web_server 配置中设置了 ota: false，只需删除该行，并且不要添加 web_server OTA 平台。

示例配置

带有 Web Server OTA 的基本设置：

# 基本配置
web_server:
  port: 80

ota:
  - platform: web_server

带有认证的 secure 设置：

# 推荐：带认证
web_server:
  port: 80
  auth:
    username: admin
    password: !secret web_password

ota:
  - platform: web_server

使用 Web 界面

导航到设备的 Web 界面 http://<device-ip>/ 或 http://<device-name>.local/
如果已启用认证，请输入您的用户名和密码
向下滚动到”OTA Update”部分
点击”Choose File”并选择您的固件文件（firmware.bin ）
点击”Update”以开始上传
等待上传完成 - 设备将自动重启并加载新固件

WARNING

OTA 更新时始终使用 firmware.bin 或 firmware.ota.bin 文件，不要使用 firmware.factory.bin 文件
Web 界面在更新过程中可能会无响应 - 这是正常的
更新期间请勿关闭设备电源

使用命令行

esphome upload 和 esphome run 也可以通过 web_server OTA 平台上传固件。这在以下情况下很有用：

设备仅在 ota: 下配置了 platform: web_server（没有原生 API OTA）。
您不再拥有 ESPHome OTA 密码但仍知道 web_server 的 auth 凭证。
原生 API OTA 端口被防火墙阻止，而配置的 web_server 端口（HTTP，默认为 80）仍可访问。

当 platform: web_server 是唯一配置的 OTA 平台时，CLI 会自动选择它。当同时配置了 platform: esphome 和 platform: web_server 时， CLI 默认优先使用原生 API OTA 路径，因为原生协议使用带有哈希非挑战响应的认证（密码不会通过网络传输），而 web_server 路径则依赖 HTTP Basic 认证。传递 --ota-platform web_server 可以强制使用 HTTP 路径：

# 当 web_server OTA 是唯一配置的平台时自动选择：
esphome upload <config.yaml>

# 在 upload 或 run 中强制使用 web_server OTA 路径：
esphome upload <config.yaml> --ota-platform web_server
esphome run <config.yaml> --ota-platform web_server

如果配置了 web_server 的 auth 块，CLI 会将这些凭证作为 HTTP Basic Authorization 头发送。设备通过 WWW-Authenticate: Basic 进行挑战，因此凭证将以明文形式通过网络传输。--ota-platform web_server 路径 完全不使用 ESPHome OTA 密码；它只使用 web_server 的 auth 凭证。

WARNING

HTTP Basic 认证凭证在本地网络上以明文发送，与 Web UI 上传流程相同。将 web_server 的 auth 用户名/密码视为 “仅限本地网络”的密钥。如果有选择，优先使用 platform: esphome 进行 CLI 上传，因为它永远不会通过网络发送密码。

Web Server OTA 更新

配置变量

从旧版配置迁移

示例配置

使用 Web 界面

使用命令行

另请参阅