ESP32 自带 2.4GHz WiFi,是它比传统 Arduino UNO 最讨喜的地方。但不少新手第一块板子点亮后,卡在联网这一步:扫描扫不出、begin 之后一直等不到 connected、路由器一重启板子就永久掉线。这篇把 WiFi.h 里最核心的三件事一次讲清——扫描周边网络、连接与状态判断、断线后自动重连,代码全部取自 Random Nerd Tutorials 的 ESP32 WiFi Functions 教程,可直接烧录验证。

准备工作:WiFi.h 与两种模式
所有操作只需要一个头文件。WiFi.h 随 ESP32 Arduino 核心自带,装好核心包就有,PlatformIO 新建项目也会自动引入,不用额外装库。
#include "WiFi.h"ESP32 有三种 WiFi 模式,用 WiFi.mode() 切换:WIFI_STA 是站点模式,板子像手机一样去连路由器;WIFI_AP 是软接入点模式,板子自己发热点;WIFI_AP_STA 两者同时开。本文只讲 STA 模式,也就是最常见的"让 ESP32 连上你家路由器"这条线。
第一步:扫描周边网络
动手连之前,先用官方示例 WiFiScan 摸一下环境。核心就一句 WiFi.scanNetworks(),它返回找到的网络数量,再配 SSID(i)、RSSI(i)、encryptionType(i) 把每个网络的名称、信号、加密类型读出来:
/*
Example from WiFi > WiFiScan
Complete details at https://RandomNerdTutorials.com/esp32-useful-wi-fi-functions-arduino/
*/
#include "WiFi.h"
void setup() {
Serial.begin(115200);
// Set WiFi to station mode and disconnect from an AP if it was previously connected
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
Serial.println("Setup done");
}
void loop() {
Serial.println("scan start");
// WiFi.scanNetworks will return the number of networks found
int n = WiFi.scanNetworks();
Serial.println("scan done");
if (n == 0) {
Serial.println("no networks found");
} else {
Serial.print(n);
Serial.println(" networks found");
for (int i = 0; i < n; ++i) {
// Print SSID and RSSI for each network found
Serial.print(i + 1);
Serial.print(": ");
Serial.print(WiFi.SSID(i));
Serial.print(" (");
Serial.print(WiFi.RSSI(i));
Serial.print(")");
Serial.println((WiFi.encryptionType(i) == WIFI_AUTH_OPEN)?" ":"*");
delay(10);
}
}
Serial.println("");
// Wait a bit before scanning again
delay(5000);
}串口监视器设成 115200 波特率,就能看到每个网络的 SSID、括号里的 RSSI 值,带星号的是加密网络:

加密类型对应的枚举是 WIFI_AUTH_OPEN、WIFI_AUTH_WEP、WIFI_AUTH_WPA_PSK、WIFI_AUTH_WPA2_PSK、WIFI_AUTH_WPA_WPA2_PSK 和 WIFI_AUTH_WPA2_ENTERPRISE,家用路由器基本都是 WPA2_PSK 这一档。
第二步:连接与状态判断
连接只需要 begin 一句,但关键是之后要盯着状态等它连上。教程给的写法是包一个 initWiFi() 函数:
// Replace with your network credentials
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";
void initWiFi() {
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
Serial.print("Connecting to WiFi ..");
while (WiFi.status() != WL_CONNECTED) {
Serial.print('.');
delay(1000);
}
Serial.println(WiFi.localIP());
}WiFi.status() 的返回值是七个枚举,判断连接状态全靠它:
| 返回值 | 常量 | 含义 |
|---|---|---|
| 0 | WL_IDLE_STATUS | begin() 之后的临时状态 |
| 1 | WL_NO_SSID_AVAIL | 找不到这个 SSID |
| 2 | WL_SCAN_COMPLETED | 扫描完成 |
| 3 | WL_CONNECTED | 已连接 |
| 4 | WL_CONNECT_FAILED | 连接失败 |
| 5 | WL_CONNECTION_LOST | 连接丢失 |
| 6 | WL_DISCONNECTED | 已断开 |
连上之后,WiFi.localIP() 能直接拿到路由器分配的 IP。想看信号质量就打一句 WiFi.RSSI(),数值是负的 dBm,绝对值越小信号越好——-50 比 -80 强得多。教程的实测输出长这样,-64 属于能用但不算强的水平:

第三步:断线重连
这是实际部署时最要命的一步。路由器重启、信号波动,ESP32 掉线后默认不一定自己爬起来。教程给了两种方案。
方案一是轮询。每 30 秒检查一次状态,掉线就 disconnect 再 reconnect,用 millis() 做非阻塞计时,不用 delay 卡死主循环:
unsigned long currentMillis = millis();
// if WiFi is down, try reconnecting
if ((WiFi.status() != WL_CONNECTED) && (currentMillis - previousMillis >=interval)) {
Serial.print(millis());
Serial.println("Reconnecting to WiFi...");
WiFi.disconnect();
WiFi.reconnect();
previousMillis = currentMillis;
}方案二是事件驱动,更推荐。WiFi.onEvent() 注册回调,网络事件发生时自动触发,完全不用轮询。完整示例是这样:
/*
Rui Santos
Complete project details at https://RandomNerdTutorials.com/solved-reconnect-esp32-to-wifi/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files.
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
*/
#include "WiFi.h"
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";
void WiFiStationConnected(WiFiEvent_t event, WiFiEventInfo_t info){
Serial.println("Connected to AP successfully!");
}
void WiFiGotIP(WiFiEvent_t event, WiFiEventInfo_t info){
Serial.println("WiFi connected");
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
}
void WiFiStationDisconnected(WiFiEvent_t event, WiFiEventInfo_t info){
Serial.println("Disconnected from WiFi access point");
Serial.print("WiFi lost connection. Reason: ");
Serial.println(info.wifi_sta_disconnected.reason);
Serial.println("Trying to Reconnect");
WiFi.begin(ssid, password);
}
void setup(){
Serial.begin(115200);
// delete old config
WiFi.disconnect(true);
delay(1000);
WiFi.onEvent(WiFiStationConnected, WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_CONNECTED);
WiFi.onEvent(WiFiGotIP, WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_GOT_IP);
WiFi.onEvent(WiFiStationDisconnected, WiFiEvent_t::ARDUINO_EVENT_WIFI_STA_DISCONNECTED);
/* Remove WiFi event
Serial.print("WiFi Event ID: ");
Serial.println(eventID);
WiFi.removeEvent(eventID);*/
WiFi.begin(ssid, password);
Serial.println();
Serial.println();
Serial.println("Wait for WiFi... ");
}
void loop(){
delay(1000);
}三个回调分别盯着三个事件:STA_CONNECTED 是连上接入点、STA_GOT_IP 是拿到 IP、STA_DISCONNECTED 是掉线。掉线回调里除了重新 begin,还能用 info.wifi_sta_disconnected.reason 读出断开原因码,排查密码错还是路由器踢人时非常有用。注册回调会返回一个事件 ID,不需要时用 WiFi.removeEvent(id) 移除。
踩坑清单
- 连接等待用 while 循环检查 WiFi.status() 才稳,begin 之后立刻发请求是最常见的翻车点,连接本身可能耗时数秒。
- 写死 IP 用 WiFi.config(local_IP, gateway, subnet, primaryDNS),教程示例是 192.168.1.184 配网关 192.168.1.1、掩码 255.255.0.0、DNS 8.8.8.8;DNS 可以不填。
- 想改主机名,必须先调 WiFi.config(INADDR_NONE, INADDR_NONE, INADDR_NONE, INADDR_NONE) 再 WiFi.setHostname(),且放在 begin 之前;默认主机名是 espressif,改完有时还得重启路由器才生效。
- STA 掉线重连,reconnect() 有时救不回来,disconnect 后重新 begin 是更彻底的办法,实在不行 ESP.restart() 重启兜底。
- 一块 ESP32 记多个网络可以用 WiFiMulti,addAP() 加进列表后自动连信号最强的那个。
整体建议:项目里直接用事件驱动的重连写法,轮询版留给简单演示。扫描、连接、重连这三段代码背下来,ESP32 的 WiFi 基本功就齐了,后面不管接什么云服务都是在这个地基上盖楼。











这套事件驱动的重连写法确实比我原来在 loop 里轮询靠谱。之前做阳台土壤湿度上报,路由器半个月重启一次,板子就再也没上来过,后来也是照这个 WiFi.onEvent 加 STA_DISCONNECTED 回调里重新 begin 才根治的。顺便提一句,info.wifi_sta_disconnected.reason 这个原因码真的有用,我那次读到 reason=201 就是密码错,排查省了不少功夫。
扫描那段建议加上 WiFi.scanNetworks(true) 同步异步的事,不过新手先跑这个完全够用了
status 那张表收藏了,之前一直记不住 WL_NO_SSID_AVAIL 和 WL_CONNECT_FAILED 的区别
事件注册记得放 setup 里,别在回调里再 begin 自己触发自己,我踩过一次死循环