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 (Optional, string): 您的设备应该连接的 WiFi 接入点的名称（或 服务集标识符）。

• password (Optional, string): 您的 WiFi 网络的密码（或 PSK）。留空表示无密码。

• networks (Optional): 配置多个要连接的 WiFi 网络，将连接到可达的最佳网络。参见 连接多个网络。

• manual_ip (Optional): 手动配置节点的静态 IP。

  • static_ip (Required, IPv4 地址): 节点的静态 IP。
  • gateway (Required, IPv4 地址): 本地网络的网关。
  • subnet (Required, IPv4 地址): 本地网络的子网。
  • dns1 (Optional, IPv4 地址): 使用的主要 DNS 服务器。
  • dns2 (Optional, IPv4 地址): 使用的备用 DNS 服务器。

• use_address (Optional, string): 手动覆盖用于连接到 ESP 的地址。默认为自动生成的值。例如，如果您更改了静态 IP 并希望 OTA 刷新到之前配置的 IP 地址。

• ap (Optional): 在节点上启用接入点模式。

  • ssid (Optional, string): 要创建的接入点名称。留空则使用设备名称。

  • password (Optional, string): 接入点的密码。留空表示无密码。

  • channel (Optional, int): AP 应该运行的通道，从 1 到 14。 默认为 1。

  • manual_ip (Optional): 手动设置 AP 的 IP 选项。与站点模式的 manual_ip 选项相同。

  • ap_timeout (Optional, Time): 启用配置的后备热点之前等待的时间。可以通过设置为 0s 来禁用，这需要通过其他方式（例如：通过按钮按下）手动启动 AP。默认为 90s。

• domain (Optional, string): 设置用于上传的节点主机名的域。 例如，如果设置为 .local，所有上传将发送到 <HOSTNAME>.local。 默认为 .local。

• reboot_timeout (Optional, Time): 当没有 WiFi 连接存在时，等待重新启动的时间。可以通过设置为 0s 来禁用，但请注意底层 IP 栈目前似乎有 WiFi 问题，需要完全重启才能使接口恢复正常工作。默认为 15min。 在接入点模式下不适用。

• power_save_mode (Optional, string): WiFi 接口的省电模式。 参见 省电模式

• output_power (Optional, string): WiFi 接口的 TX 功率，从 8.5dB 到 20.5dB。ESP8266 默认为 20dB，20.5dB 可能导致意外重启。

• fast_connect (Optional, boolean): 如果启用，直接连接到 WiFi 网络而不先进行完整扫描。这可以显著提高连接速度（从而降低功耗）。默认为 off。 缺点是此选项会连接到 ESP 看到的第一个网络，即使该网络很远且 有更好的网络可用。如果配置了多个网络，首先测试上次成功连接的那个。 如果失败，则按声明的顺序逐个测试所有网络，从列表中的第一个开始。

  NOTE

  虽然 fast_connect 跳过初始扫描，但如果连接尝试失败，ESPHome 仍会执行扫描 以查找可用网络。对于隐藏网络，在网络配置上使用 hidden: true（参见 连接多个网络）以确保设备始终无需扫描即可连接。 请注意，将网络标记为隐藏会阻止 ESPHome 找到最佳接入点进行连接， 因此设备可能不会连接到信号强度最佳的 AP。

• min_auth_mode (Optional, string): 仅适用于 esp32 和 esp8266。设置设备连接到接入点时接受的最小 WiFi 认证模式。这控制您的设备允许的最弱加密。可能的值有：

  • WPA - 允许 WPA、WPA2 和 WPA3 网络（最不安全，使用有已知漏洞的 TKIP 加密）
  • WPA2 - 允许 WPA2 和 WPA3 网络（推荐，使用 AES 加密）
  • WPA3 - 仅允许 WPA3 网络（最安全，仅 ESP32）

  ESP32 默认为 WPA2，ESP8266 默认为 WPA（将在 2026.6.0 更改为 WPA2）。

  安全警告： 设置 min_auth_mode: WPA 允许连接使用已弃用的 WPA/TKIP 加密的网络， 这有已知的安全漏洞。仅对无法升级到 WPA2 或 WPA3 的旧路由器使用此设置。 如果您的路由器支持 WPA2 或更新版本，请使用默认的 WPA2 设置以获得更好的安全性。

• passive_scan (Optional, boolean): 如果启用，设备将以被动方式执行 WiFi 扫描。 默认为 false。

• enable_btm (Optional, bool): 仅适用于 esp32。启用 802.11v BSS 过渡管理支持。

• enable_rrm (Optional, bool): 仅适用于 esp32。启用 802.11k 无线资源管理支持。

• post_connect_roaming (Optional, bool): 为固定设备启用基本的连接后 漫游。连接到非隐藏网络后，设备将定期检查具有相同 SSID 且信号明显更好（+10 dB）的接入点，如果找到则切换。 这有助于设备从连接到次优 AP 的情况中恢复（例如，AP 重启或站点断电后）。 如果启用了 enable_btm 或 enable_rrm 则自动禁用。参见 连接后漫游。默认为 true。

• on_connect (Optional, Automation): 建立连接时要执行的动作。

• on_disconnect (Optional, Automation): 连接断开时要执行的动作。

• enable_on_boot (Optional, boolean): 如果启用，WiFi 接口将在启动时启用。默认为 true。

• use_psram (Optional, boolean): 仅适用于 ESP32，请求 WiFi 库尝试从 PSRAM 分配内存。 默认为 false。需要配置 PSRAM。

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

接入点模式

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

wifi:
  ap:
    ssid: "客厅后备热点"
    password: "W1PBGyrokfLz"

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

wifi:
  ap: {}

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

wifi:
  ap:
    password: "W1PBGyrokfLz"

用户输入的凭据

某些组件如 Captive Portal、Improv Serial 和 Esp32 Improv 使用户能够发送和保存 Wi-Fi 凭据到设备。从 2022.11.0 开始， 只要配置文件中未设置凭据，并且固件是通过 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 上：

1. AP 重启：当接入点重启（固件更新或其他原因）时，设备连接到另一个信号较差的 AP。没有漫游，它会永久停留在较差的 AP 上，即使原始更好的 AP 恢复在线后也永远不会返回。

2. 全站断电：断电后恢复供电时，设备连接到最先恢复的 AP，这可能是最差的选择（例如，最远的那个）。没有漫游，它会永久停留在此次优 AP 上，即使更好的 AP 上线后也是如此。

3. 开箱配置：当通过 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 (Optional, string): SSID 或 WiFi 网络名称。

• password (Optional, string): 用于认证的密码。留空表示无密码。

• manual_ip (Optional): 使用此网络时手动配置节点的静态 IP。注意， 当每个网络使用不同的静态 IP 地址时，需要设置 use_address，因为 ESPHome 无法推断节点连接到哪个网络。

  • static_ip (Required, IPv4 地址): 节点的静态 IP。
  • gateway (Required, IPv4 地址): 本地网络的网关。
  • subnet (Required, IPv4 地址): 本地网络的子网。
  • dns1 (Optional, IPv4 地址): 使用的主要 DNS 服务器。
  • dns2 (Optional, IPv4 地址): 使用的备用 DNS 服务器。

• eap (Optional): 参见 企业认证。

• channel (Optional, int): 网络的通道（1-14）。如果给定，则仅连接到此通道上的网络。

• bssid (Optional, string): 连接的 BSSID（MAC 地址）。BSSID 必须由六个 两位十六进制值组成，用冒号字符（“:”）分隔。所有字母必须大写。

• hidden (Optional, boolean): 此网络是否隐藏。默认为 false。 如果添加此选项，还必须指定 ssid。

  TIP

  如果您的网络不广播其 SSID，请设置 hidden: true。这确保设备尝试连接 使用隐藏网络模式，而不先扫描可见网络。请注意，当连接到隐藏网络时， ESPHome 无法确定哪个接入点信号最好，可能导致连接到多个 AP 共享相同 SSID 时信号较弱的 AP。

• priority (Optional, int): 此网络的优先级（范围：-128 到 127）。选择优先级最高的网络。 每次连接失败后，优先级减一。 如果所有跟踪的 BSSID 具有相同的优先级，它们会自动重置为 0 重新开始。 默认为 0。

示例：连接隐藏网络

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

企业认证

ESP32 和 ESP8266 支持 WPA2_EAP 企业认证。 要配置此功能，必须使用 连接多个网络 样式的配置。 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 (Optional, string): 传递给 EAP 认证服务器的外部身份。 这对于 EAP-TLS 是必需的。

• username (Optional, string): 提交给认证服务器的用户名。

• password (Optional, string): 提交给认证服务器的密码。 对于 EAP-TLS，此密码可能设置为解密私钥。

• certificate_authority (Optional, string): 验证认证服务器时使用的 PEM 编码证书的路径。

• certificate (Optional, string): 用于 EAP-TLS 认证的 PEM 编码证书的路径。

• key (Optional, string): 与 certificate 匹配的用于 EAP-TLS 认证的 PEM 编码私钥的路径。 可选地使用 password 加密。

• ttls_phase_2 (Optional, string): EAP-TTLS 的第二阶段认证方法。 可以是 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 和密码，可选择将其保存在持久内存中，以便下次启用 WiFi 接口时连接到保存的接入点。

on_...:
  then:
    - wifi.configure:
        ssid: "MyHomeNetwork"
        password: "VerySafePassword"
        save: true
        timeout: 30000ms
        on_connect:
          - logger.log: "已连接到 WiFi！"
        on_error:
          - logger.log: "连接 WiFi 失败！"

配置变量

• ssid (Required, string, templatable): WiFi 接入点的名称。

• password (Required, string, templatable): WiFi 接入点的密码。 留空表示无密码。

• save (Optional, boolean, templatable): 如果设置为 true，SSID 和密码将保存在持久内存中。默认为 true。

• timeout (Optional, Time, templatable): 等待建立连接的时间。 默认为 30 秒。

• on_connect (Optional, Automation): 建立连接时要执行的动作。

• on_error (Optional, Automation): 连接失败时要执行的动作。

条件

wifi.connected 条件

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

on_...:
  if:
    condition:
      wifi.connected:
    then:
      - logger.log: WiFi 已连接！

等效的 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 处于活动状态！

等效的 lambda 表达式是 id(wifi_id).is_ap_active()。

另见

• Captive Portal
• WiFi 信息文本传感器
• WiFi 信号传感器
• 网络组件
• Ethernet 组件
• 原生 API
• API Reference: wifi_component.h