Web 服务器组件

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

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

# 示例配置项
web_server:
  port: 80

配置变量

port (Optional, int): Web 服务器应该打开其套接字的端口。
css_url (Optional, url): 应该用于 CSS 样式表的 URL。默认为 https://oi.esphome.io/v1/webserver-v1.min.css（更新将转到 v2、v3 等）。可以设置为空字符串。
css_include (Optional, 本地文件): 要包含在 Web 服务器索引页面中的本地文件路径。此文件的内容将作为 /0.css 提供服务，并由内部 Web 服务器用作 CSS 样式表。当构建没有互联网访问的设备时很有用，您想使用内置 AP 和 Web 服务器。
js_url (Optional, url): 应该用于 JS 脚本的 URL。默认为 https://oi.esphome.io/v1/webserver-v1.min.js。可以设置为空字符串。
js_include (Optional, 本地文件): 要包含在 Web 服务器索引页面中的本地文件路径。此文件的内容将作为 /0.js 提供服务，并由内部 Web 服务器用作 JS 脚本。当构建没有互联网访问的设备时很有用，您想使用内置 AP 和 Web 服务器。
auth (Optional): 启用带有用户名和密码的简单 Digest 认证。
- username (Required, string): 用于认证的用户名。
- password (Required, string): 用于认证检查的密码。
include_internal (Optional, boolean): internal 实体是否应该显示在 Web 界面上。默认为 false。
enable_private_network_access (Optional, boolean): 启用对私有网络访问和私有网络访问权限提示的支持。默认为 true。
log (Optional, boolean): 打开或关闭 Web 服务器内的日志功能。默认为 true。
ota (Optional, boolean): 显式禁用通过 Web 服务器界面的 OTA 更新。只接受 false。此选项通常在您同时配置了 web_server 和 captive_portal 时使用，并且您希望 OTA 更新仅通过强制门户可用。由于 captive_portal 自动加载 Web 服务器 OTA 平台，将此设置为 false 可以防止通过常规 Web 界面进行 OTA 访问，同时保持强制门户访问。要为 Web 服务器启用 OTA，请改用 web_server OTA 平台。
id (Optional, ID): 手动指定用于代码生成的 ID。
local (Optional, boolean): 在本地包含支持性 javascript，允许在没有互联网访问的情况下工作。默认为 false。
compression (Optional, string): 当启用 local 时用于嵌入 Web 资源的压缩算法。选项为 gzip 或 br（Brotli）。Brotli 提供更小的嵌入 Web 资源（比 gzip 小约 10%），但某些浏览器仅支持通过 HTTPS 连接的 Brotli。由于 ESPHome 设备通常通过 HTTP 提供，建议使用 gzip 以获得最大兼容性。默认为 gzip。
version (Optional, string): 1、2 或 3。版本 1 显示为表格。版本 2 使用 Web 组件并具有更多功能。版本 3 使用 HA 样式。默认为 2。
sorting_groups (Optional, list): 仅在 version: 3 上可用。用于分组实体的组 ID 和名称列表。请参阅 Web 服务器实体分组。
- id (Required, ID): 手动指定用于组的 ID。
- name (Required, string): 表示组名称的字符串，显示为组的标题
- sorting_weight (Optional, float): 表示组权重的浮点数。具有较小
sorting_weight 的组将首先显示。默认为 50

为了节省闪存大小，用于在根页面上显示简单用户界面的 CSS 和 JS 文件在外部托管在 oi.esphome.io。如果您想使用自己的服务，请在配置中使用 css_url 和 js_url 选项。

NOTE

通过 Web 界面进行 OTA 更新

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

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

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

要显式禁用 Web 服务器的 OTA 更新，同时保持强制门户启用（当配置强制门户时很有用，因为它自动启用 Web 服务器 OTA）：

# 仅为 web_server 禁用 OTA 更新
# 强制门户仍将具有 OTA 访问权限，因为它自动加载 web_server OTA 平台
web_server:
  ota: false

captive_portal:  # 此组件自动启用 OTA

有关更多信息，请参阅 Web 服务器。

示例配置

启用 HTTP 认证：

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

IMPORTANT

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

使用版本 1 用户界面：

# 示例配置项
web_server:
  port: 80
  version: 1

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

# 示例配置项
web_server:
  local: true

在使用强制门户时禁用 Web 服务器的 OTA 更新（常见安全设置）：

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

# 强制门户自动启用 web_server OTA 平台
# OTA 仅在强制门户活动时可访问
captive_portal:

高级用法

以下假设文件副本具有本地路径 - 这取决于配置。

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

web_server:
  port: 80
  version: 1
  css_include: "../../../esphome-docs/_static/webserver-v1.min.css"
  css_url: ""
  js_include: "../../../esphome-docs/_static/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。 我的传感器 2 显示在 我的传感器 1 之前

示例配置：

sensor:
  - platform: template
    name: "我的传感器 1"
    web_server:
      sorting_weight: 10
  - platform: template
    name: "我的传感器 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: "时间设置"
      sorting_weight: 10
    - id: sorting_group_number_settings
      name: "数字设置"
      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