ESP32 WiFi联网实操:扫描连接与断线重连

2026-11-18 13:29:07 56阅读 所属项目:ESP32 开发板

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

ESP32 WiFi 联网教程

准备工作: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 值,带星号的是加密网络:

ESP32 WiFi 扫描结果串口输出

加密类型对应的枚举是 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() 的返回值是七个枚举,判断连接状态全靠它:

返回值常量含义
0WL_IDLE_STATUSbegin() 之后的临时状态
1WL_NO_SSID_AVAIL找不到这个 SSID
2WL_SCAN_COMPLETED扫描完成
3WL_CONNECTED已连接
4WL_CONNECT_FAILED连接失败
5WL_CONNECTION_LOST连接丢失
6WL_DISCONNECTED已断开

连上之后,WiFi.localIP() 能直接拿到路由器分配的 IP。想看信号质量就打一句 WiFi.RSSI(),数值是负的 dBm,绝对值越小信号越好——-50 比 -80 强得多。教程的实测输出长这样,-64 属于能用但不算强的水平:

ESP32 WiFi RSSI 信号强度输出

第三步:断线重连

这是实际部署时最要命的一步。路由器重启、信号波动,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 基本功就齐了,后面不管接什么云服务都是在这个地基上盖楼。


作者:写launch的皮皮
链接:https://www.aiddithome.com/p/4f7802b92f69a.html
本作版权归作者所有,未经允许请勿转载。若存在违规行为,您可以点击 “举报”。


登录 后发表评论
4条评论
胶佬憨憨
1楼 · 2026-11-18 13:29:42

这套事件驱动的重连写法确实比我原来在 loop 里轮询靠谱。之前做阳台土壤湿度上报,路由器半个月重启一次,板子就再也没上来过,后来也是照这个 WiFi.onEvent 加 STA_DISCONNECTED 回调里重新 begin 才根治的。顺便提一句,info.wifi_sta_disconnected.reason 这个原因码真的有用,我那次读到 reason=201 就是密码错,排查省了不少功夫。

只看不说话
2楼 · 2026-11-18 13:29:42

扫描那段建议加上 WiFi.scanNetworks(true) 同步异步的事,不过新手先跑这个完全够用了

刷视频进来围观
3楼 · 2026-11-18 13:29:42

status 那张表收藏了,之前一直记不住 WL_NO_SSID_AVAIL 和 WL_CONNECT_FAILED 的区别

好说好说
4楼 · 2026-11-18 13:29:42

事件注册记得放 setup 里,别在回调里再 begin 自己触发自己,我踩过一次死循环