Web 服务器组件

web_server 组件在节点上创建一个简单的 Web 服务器，可以通过任何浏览器和简单的 REST API 访问。请注意，启用此组件 将占用大量内存，并可能降低稳定性，尤其是在 ESP8266 上。

Web 服务器版本 1

Web 服务器版本 2

Web 服务器版本 3

要在浏览器中访问 Web 服务器，可以使用节点的 IP 地址，或者 通过 mDNS 使用 <node_name>.local/（注意末尾的正斜杠）。

# 示例配置条目
web_server:
  port: 80

配置变量

• port (可选, int): Web 服务器应打开其套接字的端口。

• css_url (可选, url): 应使用的 CSS 样式表 URL。默认 为 https://oi.esphome.io/v1/webserver-v1.min.css（更新将转到 v2、v3 等）。可以设置为空字符串。

• css_include (可选, 本地文件): 要包含在 Web 服务器索引页面中的本地文件路径。 此文件的内容将作为 /0.css 提供，并作为内部 Web 服务器的 CSS 样式表使用。 在没有互联网访问权限的情况下构建设备时很有用，此时你希望使用内置 AP 和 Web 服务器。

• js_url (可选, url): 应使用的 JS 脚本 URL。默认 为 https://oi.esphome.io/v1/webserver-v1.min.js。可以设置为空字符串。

• js_include (可选, 本地文件): 要包含在 Web 服务器索引页面中的本地文件路径。 此文件的内容将作为 /0.js 提供，并作为内部 Web 服务器的 JS 脚本使用。 在没有互联网访问权限的情况下构建设备时很有用，此时你希望使用内置 AP 和 Web 服务器。

• auth (可选): 启用使用用户名和密码的 HTTP 认证。

  • username (必选, string): 用于认证的用户名。

  • password (必选, string): 用于认证的密码。

  • type (可选, string): HTTP 认证方案。两者在浏览器中显示相同的登录提示 ；区别在网络层面。可选：

    • basic (默认): 在每次请求中以易反转（Base64）形式发送密码。
    • digest: 仅发送哈希，密码不通过网络。推荐。

    当前默认是 basic，但在 ESPHome 2027.1.0 中将更改为 digest；在 该版本之后显式设置 type: basic 以保留它。使用 digest 时，REST API 客户端 也必须请求它（例如 curl --digest）；普通的 basic 客户端将被拒绝。

• include_internal (可选, boolean): internal 实体是否应显示在 Web 界面上。默认为 false。

• enable_private_network_access (可选, boolean): 启用 私有网络访问 和 私有网络访问权限提示 的支持。 默认为 true。

• log (可选, boolean): 打开或关闭 Web 服务器内部的日志功能。默认为 true。

• ota (可选, boolean): 显式禁用通过 Web 服务器界面的 OTA 更新。仅接受 false。 此选项通常在你同时配置了 web_server 和 captive_portal，并且希望 OTA 更新仅通过 captive portal 可用时使用。由于 captive_portal 自动加载 Web 服务器的 OTA 平台，将其设置为 false 可以防止通过常规 Web 界面访问 OTA，同时 维持对 captive portal 的访问。要为 Web 服务器启用 OTA，请使用 web_server OTA 平台。

• id (可选, ID): 手动指定用于代码生成的 ID。

• local (可选, boolean): 在本地包含支持脚本，使其可以在无互联网访问的情况下工作。 默认为 false。

• compression (可选, string): 启用 local 时嵌入式 Web 资源使用的压缩算法。 可选 gzip 或 br（Brotli）。Brotli 提供的嵌入式 Web 资源更小（比 gzip 小约 10%），但某些 浏览器仅支持 HTTPS 连接上的 Brotli。由于 ESPHome 设备通常通过 HTTP 提供，因此 建议为最大兼容性使用 gzip。默认为 gzip。

• version (可选, string): 1、2 或 3。版本 1 显示为表格。版本 2 使用 Web 组件 并具有更多功能。版本 3 使用 HA 样式。默认为 2。版本 1 已弃用，将在 2027.1.0 中移除；请迁移到版本 2（默认）或版本 3。

• sorting_groups (可选, list): 仅在 version: 3 上可用。一个组 ID 和名称列表，用于 对实体进行分组。参见 Web 服务器实体分组。

  • id (必选, ID): 手动指定用于组的 ID。
  • name (必选, string): 表示组名的字符串，作为组的标题显示。
  • sorting_weight (可选, float): 表示组权重的浮点数。sorting_weight 更小的 组将首先显示。默认为 50。

为节省 Flash 空间，根页面显示简单用户 界面所使用的 CSS 和 JS 文件托管在 oi.esphome.io 上。如果你想使用自己的服务，请在 配置中使用 css_url 和 js_url 选项。

NOTE

OTA Updates via Web Interface

ota 选项已从 web_server 组件移动到其自己的 OTA 平台。

要通过 Web 界面启用 OTA 更新，请使用新的 web_server OTA 平台：

# 通过 Web 界面启用 OTA 更新
ota:
  - platform: web_server

要显式禁用 Web 服务器的 OTA 更新，同时为 captive portal 保持启用 （在配置了 captive portal 时很有用，因为它会自动启用 Web 服务器 OTA）：

# 仅禁用 web_server 的 OTA 更新
# Captive portal 仍将具有 OTA 访问权限，因为它会自动加载 Web 服务器 OTA 平台
web_server:
  ota: false

captive_portal:  # 此组件会自动启用 OTA

更多信息参见 Web 服务器。

安全

Web 服务器暴露了一个 HTTP API，用于查看和控制你的设备的实体。当 web_server OTA 平台 启用时，它也可以更新固件。

WARNING

Web 服务器在设计上没有任何跨站保护。它不进行 CSRF、Origin 或 Referer 检查，并使用 宽松的 CORS 策略，因此可以从其他来源调用，包括你与设备处于同一 网络时打开的网页。它唯一的访问控制是 auth: 选项和设备所在的网络。请将其视为 开放控制界面，除非你启用了 auth:。

建议：

• 如果设备处于你不完全信任的网络上，请启用 auth:。
• 将设备保持在受信任的、隔离的网络上，切勿将 Web 服务器暴露给互联网。参见 安全最佳实践。
• 如果没有 auth: 而启用了 Web OTA，任何可以访问设备的人（包括通过浏览器跨来源） 都可以上传固件。使用 Web auth: 保护它，在不需要时禁用 Web OTA（ota: false），或使用 密码保护的 原生 OTA。

此跨来源行为是否是漏洞，项目 威胁模型 给出了答案：它是有意为之的，不是防御 边界。

配置示例

启用 HTTP 认证：

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

IMPORTANT

使用 Web 服务器时请始终启用认证。建议参见 安全最佳实践 指南。

使用版本 1 用户界面：

WARNING

版本 1 已弃用，将在 2027.1.0 中移除；请迁移到版本 2（默认）或版本 3。

# 示例配置条目
web_server:
  port: 80
  version: 1

客户端不需要互联网/内网（所有资源都内联、压缩并从 Flash 提供）：

# 示例配置条目
web_server:
  local: true

在使用 captive portal 时禁用 Web 服务器的 OTA 更新（常见安全设置）：

# 示例配置条目
web_server:
  port: 80
  ota: false  # 禁用通过常规 Web 界面的 OTA

# Captive portal 会自动启用 Web 服务器 OTA 平台
# 仅当 captive portal 处于活动状态时 OTA 才可访问
captive_portal:

高级用法

以下假设文件副本使用本地路径——这取决于配置。

web_server 版本 1 配置示例，从本地文件夹包含 CSS 和 JS。 CSS 和 JS URL 设置为空值，因此此设备显示其 Web 界面不需要互联网访问。

web_server:
  port: 80
  version: 1
  css_include: "<some_folder>/webserver-v1.min.css"
  css_url: ""
  js_include: "<some_folder>/webserver-v1.min.js"
  js_url: ""

web_server 版本 2 配置示例，从本地文件包含 JS。 CSS 和 JS URL 设置为空值，因此此设备显示其 Web 界面不需要互联网访问。 V2 将 CSS 嵌入 JS 文件中，因此不需要，不过你也可以包含自己的 CSS。

# V2 示例配置条目
web_server:
  js_include: "./v2/www.js"
  js_url: ""
  version: 2

将 https://oi.esphome.io/v2/www.js 复制到你的 yaml 文件夹中的 V2 文件夹。

版本 3 功能

实体排序

版本 3 支持实体的排序。 你可以为每个实体设置 sorting_weight。 较小的数字将首先显示，默认为 50。 My Sensor 2 在 My Sensor 1 之前显示。

配置示例：

sensor:
  - platform: template
    name: "My Sensor 1"
    web_server:
      sorting_weight: 10
  - platform: template
    name: "My Sensor 2"
    web_server:
      sorting_weight: -1

实体分组

web_server 版本 3 允许在自定义组中对实体进行分组。 可以通过提供 sorting_weight 对组进行排序。sorting_weight 较小的组将首先显示。 如果你没有在组件上提供 web_server_sorting_group，则 entity_category 将被用作组。

配置示例：

web_server:
  version: 3
  sorting_groups:
    - id: sorting_group_time_settings
      name: "Time Settings"
      sorting_weight: 10
    - id: sorting_group_number_settings
      name: "Number settings"
      sorting_weight: 20

datetime:
  - platform: template
    ...
    web_server:
      sorting_group_id: sorting_group_time_settings

number:
  - platform: template
  ...
    web_server:
      sorting_group_id: sorting_group_number_settings

滑块模式中的 Number

你可以通过移动滑块来更改值。 如果要输入精确数字，可以点击并按住当前值。将出现一个弹出输入框，你可以在 其中输入数字，然后按回车键确认输入。

展开控制和日志

双击任何组标题即可展开控制以充满整个屏幕。 日志也可以这样做。

展开的控制

展开的日志

传感器值图表

点击任何传感器，将展开该传感器的历史值图表。

参见

• Event Source API
• REST API
• Prometheus 组件
• API 参考：web_server.h