WiFi 组件

此 ESPHome 核心组件为你设置到接入点的 WiFi 连接。你需要有一个网络配置（Wifi 或 Ethernet），否则 ESPHome 将在配置验证阶段失败。你也不能同时设置 Wifi 和 Ethernet（即使你的 ESP 同时具有这两者）。

建议为你的节点提供静态 IP，因为这可以大幅改善连接时间。

# 示例配置条目
wifi:
  ssid: MyHomeNetwork
  password: VerySafePassword

  # 可选的手动 IP
  manual_ip:
    static_ip: 192.168.0.123
    gateway: 192.168.0.1
    subnet: 255.255.255.0

# 强烈建议使用 secrets
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

TIP

关于包括 min_auth_mode 配置在内的 WiFi 安全建议，请参见安全最佳实践指南。

配置变量

ssid (可选, string): 你的设备应连接的 WiFi 接入点的名称（或服务集标识符）。
password (可选, string): 你的 WiFi 网络的密码（或 PSK）。无密码则留空。
networks (可选): 配置多个 WiFi 网络进行连接，将连接到可到达的最好的网络。参见连接到多个网络。
manual_ip (可选): 手动配置节点的静态 IP。
- static_ip (必选, IPv4 address): 你节点的静态 IP。
- gateway (必选, IPv4 address): 本地网络的网关。
- subnet (必选, IPv4 address): 本地网络的子网。
- dns1 (可选, IPv4 address): 要使用的主 DNS 服务器。
- dns2 (可选, IPv4 address): 要使用的备用 DNS 服务器。
use_address (可选, string): 手动覆盖用于连接到 ESP 的地址。默认为自动生成值。例如，如果你更改了静态 IP，并希望 OTA 刷写到之前配置的 IP 地址。
ap (可选): 在节点上启用接入点模式。
- ssid (可选, string): 要创建的接入点名称。留空则使用设备名称。
- password (可选, string): 接入点的密码。无密码则留空。
- channel (可选, int): AP 应在 1 到 14 之间工作的信道。默认为 1。
- manual_ip (可选): 为 AP 手动设置 IP 选项。与 station 模式的 manual_ip 相同选项。
- ap_timeout (可选, Time): 启用已配置备用热点之前的时间。设置为 0s 可禁用，这需要手动启动 AP（例如，从按钮按下）。默认为 90s。
domain (可选, string): 设置上传使用的节点主机名的域。例如，如果设置为 .local，所有上传都将发送到 <HOSTNAME>.local。默认为 .local。
reboot_timeout (可选, Time): 在没有 WiFi 连接存在时重启前等待的时间。可以通过设置为 0s 来禁用，但请注意，底层 IP 栈当前似乎在 WiFi 上存在问题，需要完全重启才能使接口恢复工作。默认为 15min。在接入点模式下不适用。
power_save_mode (可选, string): WiFi 接口的省电模式。参见省电模式。
output_power (可选, string): WiFi 接口的 TX 功率，从 8.5dB 到 20.5dB。ESP8266 默认为 20dB，20.5dB 可能会导致意外的重启。
fast_connect (可选, boolean): 如果启用，直接连接到 WiFi 网络，而不进行完整扫描。这可以显著改善连接时间（从而降低功耗）。默认为 off。缺点是这个选项会连接到 ESP 看到的第一个网络，即使该网络非常远且有更好的可用。如果配置了多个网络，先测试最近一次成功连接的网络。如果失败，则按声明的顺序依次测试所有网络，从列表中的第一个开始。

此选项除了布尔值外，还可以接受一个设置块：
```
wifi:
  # ...
  fast_connect:
    enabled: true
    storage: rtc
```
- enabled (可选, boolean): fast connect 是否启用。使用块形式时默认为 true。
- storage (可选, string): 在每次成功连接后 fast connect 保存的连接详情（BSSID 和 channel）的持久化位置。可选：
  - flash：在断电后仍能保留，但每次保存会稍微磨损 Flash。
  - rtc：存储在 RTC 内存中，在软件重启和深度睡眠后保留，但断电时不保留，并且避免了 Flash 磨损。适合经常从深度睡眠唤醒的电池供电设备。
  ESP8266 默认为 rtc，ESP32 默认为 flash，匹配每个平台之前的行为。在没有 RTC 支持存储的平台（RP2040 以及没有 RTC 内存的 ESP32-C2 和 C61 变体）上，仅 flash 可用，rtc 会被拒绝。
NOTE

虽然 fast_connect 跳过初始扫描，但如果连接尝试失败，ESPHome 仍然会执行扫描以查找可用网络。对于隐藏网络，请在网络配置上使用 hidden: true（参见连接到多个网络），以确保设备始终无需扫描即可连接。注意，将网络标记为隐藏会阻止 ESPHome 找到最佳接入点，因此设备可能无法连接到信号最强的 AP。
min_auth_mode (可选, string): 仅在 esp32 和 esp8266 上。设置设备连接接入点时将接受的最低 WiFi 认证模式。这控制你的设备允许的最弱加密。可能的值有：
- WPA - 允许 WPA、WPA2 和 WPA3 网络（安全性最低，使用存在已知漏洞的 TKIP 加密）
- WPA2 - 允许 WPA2 和 WPA3 网络（推荐，使用 AES 加密）
- WPA3 - 仅允许 WPA3 网络（安全性最高，仅限 ESP32）
ESP32 和 ESP8266 默认为 WPA2。

安全警告： 设置 min_auth_mode: WPA 允许连接到使用已弃用 WPA/TKIP 加密的网络，这些网络存在已知安全漏洞。仅对无法升级到 WPA2 或 WPA3 的旧路由器使用此设置。如果你的路由器支持 WPA2 或更新版本，请使用默认的 WPA2 设置以获得更好的安全性。
passive_scan (可选, boolean): 如果启用，则设备将以被动方式执行 WiFi 扫描。默认为 false。
enable_btm (可选, bool): 仅限 esp32。启用 802.11v BSS 转换管理支持。
enable_rrm (可选, bool): 仅限 esp32。启用 802.11k 无线电资源管理支持。
band_mode (可选, string): 仅限 esp32-c5。控制设备使用的 WiFi 频段。可选值为 AUTO（同时使用 2.4 GHz 和 5 GHz）、2.4GHZ（仅 2.4 GHz）和 5GHZ（仅 5 GHz）。如果未指定，默认为 AUTO。
phy_mode (可选, string): 仅限 esp8266。将无线电固定到特定的 802.11 PHY 模式。可选值为 AUTO、11B、11G 和 11N。默认为 AUTO，即让 SDK 保持其默认行为。ESP8266 设备使用 802.11n 时，与某些路由器存在已知的兼容性问题；你可以通过将 ESP 限制为 802.11g 来绕过它 phy_mode: 11G。
post_connect_roaming (可选, bool): 为固定设备启用基本连接后漫游。连接到非隐藏网络后，设备将定期检查具有相同 SSID 的更好的接入点，如果发现信号明显更好（+10 dB）的接入点则切换。这有助于设备从连接到次优 AP（例如，AP 重启或站点断电后）的场景中恢复。如果 enable_btm 或 enable_rrm 已启用则自动禁用。参见连接后漫游。默认为 true。
on_connect (可选, Automation): 建立连接时要执行的动作。
on_disconnect (可选, Automation): 连接断开时要执行的动作。
enable_on_boot (可选, boolean): 如果启用，WiFi 接口将在启动时启用。默认为 true。
use_psram (可选, boolean): 仅限 ESP32，要求 WiFi 库尝试从 PSRAM 分配内存。默认为 false。需要配置 PSRAM。
id (可选, ID): 手动指定用于代码生成的 ID。

接入点模式

ESPHome 有一个可选的”接入点模式”。如果将 ap: 包含在你的 wifi 配置中，ESPHome 将自动设置一个你可以连接的接入点。此外，你可以在同一时间指定”常规”station 模式和 AP 模式。这会导致 ESPHome 仅在无法连接到 WiFi 路由器时才启用接入点。

wifi:
  ap:
    ssid: "Livingroom Fallback Hotspot"
    password: "W1PBGyrokfLz"

你还可以创建一个简单的 ap 配置，它会将接入点设置为使用设备名称作为 ssid 且无密码。

wifi:
  ap: {}

# 或者如果你仍然希望 ap 有密码

wifi:
  ap:
    password: "W1PBGyrokfLz"

用户输入的凭据

一些组件，如 Captive Portal、Improv Serial 和 Esp32 Improv 允许用户向设备发送并保存 Wi-Fi 凭据。从 2022.11.0 开始，只要配置文件未设置凭据，并且固件上传时未擦除 Flash（通过 OTA），设备就会保留已保存的凭据。

手动 IP

如果你的节点无法连接到 WiFi 或连接过程耗时过长，给 ESP 分配一个静态 IP 地址通常是个好主意。这样，ESP 就不需要经过缓慢的 DHCP 流程。

你可以在 WiFi 配置中使用 manual_ip: 选项来实现。

wifi:
  # ...
  manual_ip:
    # 将此设置为 ESP 的 IP
    static_ip: 10.0.0.42
    # 将此设置为路由器的 IP 地址。通常以 .1 结尾
    gateway: 10.0.0.1
    # 网络的子网。255.255.255.0 适用于大多数家庭网络。
    subnet: 255.255.255.0

在配置中放入手动 IP 后，ESP 就不再需要与路由器协商动态 IP 地址，从而改善连接时间。

此外，这也有助于 OTA，例如当网络不允许 .local 地址时。当配置中有手动 IP 时， OTA 过程将自动选择它作为上传的目标。

NOTE

另见更改 ESPHome 节点名称。

省电模式

所有 ESP 的 WiFi 接口提供三种省电模式，以减少 WiFi 消耗的电量。虽然某些选项可以降低 ESP 的功耗，但它们通常也会降低 WiFi 连接的可靠性，在最高省电模式下会频繁与路由器断开连接。

NONE（省电最低，ESP8266 默认）
LIGHT（ESP32 默认）
HIGH（省电最高）

wifi:
  # ...
  power_save_mode: none

WiFi 认证模式

min_auth_mode 选项允许你控制设备接受的最低 WiFi 安全标准。这有助于确保设备仅连接到安全网络，或维持与仅支持旧加密标准的旧路由器的兼容性。

示例：最高安全性（WPA2 或更新版本）

wifi:
  ssid: MyHomeNetwork
  password: VerySafePassword
  min_auth_mode: WPA2  # 拒绝仅 WPA 的网络

示例：旧路由器支持（允许 WPA）

wifi:
  ssid: OldRouter
  password: VerySafePassword
  min_auth_mode: WPA  # 允许连接到仅 WPA 的路由器（安全性较低）

示例：现代安全性（仅 WPA3，仅限 ESP32）

wifi:
  ssid: ModernRouter
  password: VerySafePassword
  min_auth_mode: WPA3  # 仅连接到 WPA3 网络（安全性最高）

连接后漫游

连接后漫游为固定设备提供基本漫游功能，这些设备不会移动，但在初始连接后切换到更好的接入点可能有益。

为什么有此功能

如果没有连接后漫游，在三种常见场景下设备会永久卡在次优 AP 上：

AP 重启：当接入点重启（固件更新或其他原因）时，设备连接到另一个信号更差的 AP。没有漫游，设备会永久留在较差的 AP 上，即使原始更好的 AP 恢复在线也不会返回。
站点完全断电：断电恢复后，设备会连接到先恢复的 AP，这可能是最差的选择（例如，最远的一个）。没有漫游，它会永久留在这个次优 AP 上，即使更好的 AP 恢复在线。
开箱配置：当通过 captive portal、Improv 或其他方法配置 WiFi 凭据时，设备会连接而不使用 ESPHome 基于 RSSI 的 AP 选择。没有漫游，设备会永远留在那初始 AP 上，即使有更好可用。

在这三种情况下，没有连接后漫游时，唯一的修复方法是手动重启设备或等待另一次断开连接事件。

工作原理

连接到非隐藏网络后，最多检查 3 次（每 5 分钟一次）
当信号已经极好（> -49 dBm）时跳过扫描，但仍计入限制
每次扫描如果发现相同 SSID 且 +10 dB 更好信号的 AP，可能会触发漫游
3 次检查后停止检查（设备已收敛到可用的最佳 AP）
非漫游断开（例如，AP 下线）重置计数器以便重新开始
成功连接后清除所有 BSSID 优先级惩罚（原谅过去的失败）

配置

连接后漫游默认启用。要禁用它：

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  post_connect_roaming: false

802.11k/v 原生漫游

在 ESP32 上，当配置 enable_btm 或 enable_rrm 时，连接后漫游自动禁用，因为它们提供原生 802.11k/v 漫游支持：

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  enable_btm: true  # 802.11v BSS 转换管理
  enable_rrm: true  # 802.11k 无线电资源管理

限制

连接后漫游提供基本漫游支持，不提供无缝交接：

TCP 连接（包括 API）在 AP 切换期间将短暂断开。重新连接通常很快，但对客户端不透明。

要实现无缝 802.11k/v/r 漫游，请使用 ESP32 并配置 enable_btm 和 enable_rrm。

连接到多个网络

你可以给 ESPHome 提供多个 WiFi 网络进行连接。 ESPHome 然后将尝试连接到信号强度最高的一个。

要启用此模式，从你的 wifi 配置中移除 ssid 和 password 选项并将所有内容移到 networks 键下：

# 示例配置条目
wifi:
  networks:
  - ssid: FirstNetworkToConnectTo
    password: VerySafePassword
  - ssid: SecondNetworkToConnectTo
    password: VerySafePassword
  # 其他选项
  # ...

配置变量

ssid (可选, string): SSID 或 WiFi 网络名称。
password (可选, string): 用于认证的密码。无密码则留空。
manual_ip (可选): 使用此网络时手动配置节点的静态 IP。注意当在每个网络上使用不同静态 IP 地址时，必须设置 use_address，因为 ESPHome 无法推断节点连接到了哪个网络。
- static_ip (必选, IPv4 address): 你节点的静态 IP。
- gateway (必选, IPv4 address): 本地网络的网关。
- subnet (必选, IPv4 address): 本地网络的子网。
- dns1 (可选, IPv4 address): 要使用的主 DNS 服务器。
- dns2 (可选, IPv4 address): 要使用的备用 DNS 服务器。
eap (可选): 参见企业认证。
channel (可选, int): 网络的信道（1-14）。如果指定，仅连接到处于该信道的网络。
bssid (可选, string): 连接的 BSSID（MAC 地址）。BSSID 必须由六个以冒号分隔的两位十六进制值组成（“:”）。所有字母必须为大写。
hidden (可选, boolean): 此网络是否隐藏。默认为 false。如果添加此选项还必须指定 ssid。

TIP

如果你的网络不广播其 SSID，请设置 hidden: true。这确保设备在不先扫描可见网络的情况下尝试使用隐藏网络模式连接。注意，连接到隐藏网络时，ESPHome 无法确定哪个接入点具有最佳信号强度，当多个 AP 共享相同 SSID 时，可能导致连接到信号较弱的 AP。
priority (可选, int): 此网络的优先级（范围：-128 到 127）。选择优先级最高的网络。每次连接失败后，优先级减 1。如果所有跟踪的 BSSID 具有相同优先级，它们会自动重置为 0 以重新开始。默认为 0。

示例：连接到隐藏网络

wifi:
  networks:
  - ssid: MyHiddenNetwork
    password: VerySafePassword
    hidden: true

企业认证

WPA2_EAP 企业认证在 ESP32 和 ESP8266 上受支持。为了配置此功能，你必须使用连接到多个网络样式的配置。 ESP32 已知与 PEAP、EAP-TTLS 和基于证书的 EAP-TLS 一起工作。这些是高级设置，你通常需要咨询你的企业网络管理员。

# EAP 配置示例
wifi:
  networks:
  - ssid: EAP-TTLS_EnterpriseNetwork
    eap:
      username: bob
      password: VerySafePassword
      ttls_phase_2: mschapv2
  - ssid: EAP-TLS_EnterpriseNetwork
    eap:
      identity: bob
      certificate_authority: ca_cert.pem
      certificate: cert.pem
      key: key.pem

配置变量

identity (可选, string): 传递给 EAP 认证服务器的外部身份。 EAP-TLS 需要此选项。
username (可选, string): 向认证服务器展示的 username。
password (可选, string): 向认证服务器展示的密码。对于 EAP-TLS，此密码可以设置为用于解密私钥。
certificate_authority (可选, string): 用于验证认证服务器的 PEM 编码证书路径。
certificate (可选, string): 用于 EAP-TLS 认证的 PEM 编码证书路径。
key (可选, string): 用于 EAP-TLS 认证的 PEM 编码私钥路径，匹配 certificate。可选用 password 加密。
ttls_phase_2 (可选, string): EAP-TTLS 的 Phase 2 认证方法。可以是 pap、eap、mschap、mschapv2 或 chap，默认为 mschapv2。

`on_connect` / `on_disconnect` 触发器

当建立或断开 WiFi 连接时触发此触发器。

wifi:
  # ...
  on_connect:
    - switch.turn_on: switch1
  on_disconnect:
    - switch.turn_off: switch1

动作

`wifi.disable` 动作

此动作按需关闭 WiFi 接口。

on_...:
  then:
    - wifi.disable:

NOTE

禁用 WiFi 时请注意 API 组件和 WiFi 组件的重启超时。如果 WiFi 关闭时间超过任一超时的持续时间，设备将重启！

`wifi.enable` 动作

此动作按需打开 WiFi 接口。

on_...:
  then:
    - wifi.enable:

NOTE

如果不想在启动时启用 wifi，可以将 enable_on_boot 配置选项设置为 false。

`wifi.configure` 动作

此动作连接到 SSID 和 password，可选择将其保存在持久内存中，这样下次 WiFi 接口启用时，它将连接到存储的接入点。

on_...:
  then:
    - wifi.configure:
        ssid: "MyHomeNetwork"
        password: "VerySafePassword"
        save: true
        timeout: 30000ms
        on_connect:
          - logger.log: "Connected to WiFi!"
        on_error:
          - logger.log: "Failed to connect to WiFi!"

配置变量

ssid (必选, string, 可模板化): WiFi 接入点的名称。
password (必选, string, 可模板化): WiFi 接入点的密码。无密码则留空。
save (可选, boolean, 可模板化): 如果设置为 true，SSID 和 password 将保存在持久内存中。默认为 true。
timeout (可选, Time, 可模板化): 等待建立连接的时间。默认为 30 秒。
on_connect (可选, Automation): 建立连接时要执行的动作。
on_error (可选, Automation): 连接失败时要执行的动作。

条件

`wifi.connected` 条件

此条件检查 WiFi 客户端当前是否连接到 station。

on_...:
  if:
    condition:
      wifi.connected:
    then:
      - logger.log: WiFi is connected!

对应的 lambda 为 id(wifi_id).is_connected()。

`wifi.enabled` 条件

此条件检查 WiFi 当前是否已启用。

on_...:
  - if:
      condition: wifi.enabled
      then:
        - wifi.disable:
      else:
        - wifi.enable:

对应的 lambda 为 !id(wifi_id).is_disabled()。

`wifi.ap_active` 条件

此条件检查 WiFi AP 当前是否处于活动状态。

on_...:
  - if:
      condition: wifi.ap_active
      then:
        - logger.log: WiFi AP is active!

对应的 lambda 为 id(wifi_id).is_ap_active()。

WiFi 组件

配置变量

接入点模式

用户输入的凭据

手动 IP

省电模式

WiFi 认证模式

示例：最高安全性（WPA2 或更新版本）

示例：旧路由器支持（允许 WPA）

示例：现代安全性（仅 WPA3，仅限 ESP32）

连接后漫游

为什么有此功能

工作原理

配置

802.11k/v 原生漫游

限制

连接到多个网络

配置变量

示例：连接到隐藏网络

企业认证

配置变量

on_connect / on_disconnect 触发器

动作

wifi.disable 动作

wifi.enable 动作

wifi.configure 动作

配置变量

条件

wifi.connected 条件

wifi.enabled 条件

wifi.ap_active 条件

参见

`on_connect` / `on_disconnect` 触发器

`wifi.disable` 动作

`wifi.enable` 动作

`wifi.configure` 动作

`wifi.connected` 条件

`wifi.enabled` 条件

`wifi.ap_active` 条件