ESP32-S3 WiFi 连接失败排查实录：能扫描、能配置，就是连不上

环境：ESP32-S3 N8R2 · ESP-IDF v5.4 · WiFi Station 官方示例

现象：menuconfig 已正确配置 SSID/密码，手机电脑可连同一热点，ESP32 始终失败

最终结果：换路由器后 1.4 秒连上；根因是旧路由器端问题，而非代码或硬件故障

---

一、问题背景

在 ESP-IDF 官方 wifi/station 示例基础上，通过 idf.py menuconfig 配置了 WiFi 凭据，编译烧录后设备无法连接路由器。

初始配置：

| 项目 | 值 |

|------|-----|

| 芯片 | ESP32-S3 N8R2 |

| 框架 | ESP-IDF v5.4 |

| SSID | South 305 |

| 加密 | WPA2-Personal / AES |

| 频段 | 2.4 GHz |

| 开发板距离路由器 | < 0.5 米 |

手机、笔记本用相同 SSID 和密码均可正常上网，且未开启 MAC 地址过滤。

迷惑点：曾经用同一份代码成功连接过一次，之后在未改代码的情况下再次无法连接——这很容易让人怀疑是软件回归或硬件不稳定，但最终证明并非如此。

---

二、典型症状与日志

2.1 失败时的串口日志特征

I (3055) wifi station: Target AP found: SSID=South 305, RSSI=-42, channel=1, auth=4

I (3255) wifi station: wifi_init_sta finished, connecting...

I (6105) wifi:state: init -> auth (0xb0)

I (7105) wifi:state: auth -> init (0x200)

W (7105) wifi station: Disconnected: reason=2 (AUTH_EXPIRE(2)), retry=0/5

关键信息：

• 扫描成功：能发现目标 SSID，RSSI 良好（-42 dBm），auth=4 即 WPA2-PSK

• 认证失败：状态机在 init → auth 后退回 auth → init，从未进入 assoc 或四次握手

• 断开原因：以 reason=2（AUTH_EXPIRE）为主，偶发 reason=205（CONNECTION_FAIL）

• 没有 reason=15（四次握手超时）——说明大概率不是密码错误

2.2 成功时的串口日志（换路由器后）

I (1375) wifi:state: init -> auth (0xb0)

I (1375) wifi:state: auth -> assoc (0x0)

I (1385) wifi:state: assoc -> run (0x10)

I (1415) wifi:connected with BEGLE_000539, aid = 2, channel 4, WPA2-PSK, rssi: -23

I (2445) wifi station: got ip:192.168.0.199

对比可见：成功时完整走过了 auth → assoc → run 全流程。

---

三、排查过程中走过的弯路

3.1 已排除的方向

| 怀疑方向 | 排除依据 |

|----------|----------|

| menuconfig 未生效 | sdkconfig、sdkconfig.h、固件 ELF 中均含正确 SSID/密码 |

| 5 GHz 频段 | 路由器确认为 2.4 GHz |

| 密码错误 | 无 reason=15；手机同密码可连 |

| 信号太弱 | RSSI -42 ~ -51 dBm，属于良好范围 |

| 供电不足（部分场景） | 出现过 reset reason=2（外部复位），但稳定复现时多为 POWERON + AUTH_EXPIRE |

| 代码逻辑写坏 | 换回官方连接流程 + 换路由器后秒连 |

3.2 有价值的排查手段

以下几项虽未能单独解决旧路由器问题，但对定位问题层级很有帮助：

1. 在固件中打印 WiFi 断开 reason 码——避免盲目猜密码或信号

2. 连接前扫描并打印 BSSID/RSSI/auth——区分「扫不到」与「扫得到连不上」

3. 清除 WiFi NVS 缓存：esp_wifi_set_storage(WIFI_STORAGE_RAM) + esp_wifi_clear_fast_connect()

4. 关闭 WiFi 省电：esp_wifi_set_ps(WIFI_PS_NONE)

5. 擦除 PHY 射频校准数据：esp_phy_erase_cal_data_in_nvs() + 全量校准

6. 修正 Flash 大小：N8R2 为 8MB，sdkconfig 误配 2MB 会产生警告

7. 换路由器对比测试——本次的「一锤定音」手段

---

四、WiFi 断开原因码速查

排查 ESP32 WiFi 时，务必打印 wifi_event_sta_disconnected_t 中的 reason 字段：

| reason | 宏名 | 常见含义 | 优先排查 |

|--------|------|----------|----------|

| 2 | AUTH_EXPIRE | 开放认证阶段超时/被拒 | 路由器兼容性、MAC 残留会话、TX 射频 |

| 15 | 4WAY_HANDSHAKE_TIMEOUT | 四次握手超时 | 密码错误、加密方式不匹配 |

| 201 | NO_AP_FOUND | 扫描不到 SSID | 2.4G 未开、SSID 错误、信号/天线 |

| 205 | CONNECTION_FAIL | 连接过程综合失败 | 常伴随其他问题，单独出现意义有限 |

经验法则：

能扫描 + reason=2  →  优先查路由器端 / 射频 TX

能扫描 + reason=15 →  优先查密码 / WPA 模式

扫不到            →  优先查频段 / SSID / 天线

---

五、连接流程与失败点示意

┌─────────┐    ┌──────────┐    ┌──────────────┐    ┌─────────┐

│ WiFi扫描 │ → │ 开放认证  │ → │ WPA四次握手   │ → │ DHCP    │

│  (RX)   │    │ (TX+RX)  │    │ (验证密码)    │    │ 获取IP  │

└─────────┘    └──────────┘    └──────────────┘    └─────────┘

     ✅              ❌               —                  —

   RSSI -42      reason=2          未到这一步          未到这一步

本次故障卡在开放认证：ESP 能收到路由器 beacon（扫描正常），但发出的认证请求未得到正常响应。

这与「密码填错」有本质区别——密码验证发生在更后面的四次握手阶段。

---

六、最终根因

6.1 主因：旧路由器端拒绝/丢弃 ESP 的认证请求

综合以下事实：

• 同一 ESP32、同一份代码，换路由器 BEGLE_000539 后 1.4 秒内连接成功

• 旧路由器 South 305 上手机/电脑正常，仅 ESP 持续 AUTH_EXPIRE

• 同一 MAC 28:37:2f:e5:73:18 曾在旧路由器上连通过，之后失效

最合理的解释是：旧路由器对该 MAC 存在幽灵会话、接入数已满（僵尸条目占位）、或对 IoT 设备的兼容性策略，在 802.11 开放认证阶段即丢弃请求，而非密码或信号问题。

6.2 次因：射频校准数据损坏（已修复）

日志中曾出现：

W phy_init: saving new calibration data because of checksum failure

说明 Flash 中 PHY 校准数据校验失败。已通过启动时调用 esp_phy_erase_cal_data_in_nvs() 并启用全量射频校准（RF_CAL_FULL）修复。该问题可能导致「能扫到但发不出去」，但与「换路由器立刻好」相比，旧路由器仍是主因。

---

七、有效的代码与配置改动

7.1 诊断增强（建议保留）

在 WIFI_EVENT_STA_DISCONNECTED 事件中打印 reason：

wifi_event_sta_disconnected_t *disc = (wifi_event_sta_disconnected_t *)event_data;

ESP_LOGW(TAG, "Disconnected: reason=%u, retry=%d", disc->reason, retry_count);

7.2 稳定性相关配置

// 避免 NVS 中过期的 fast-connect 信息干扰

esp_wifi_set_storage(WIFI_STORAGE_RAM);

esp_wifi_clear_fast_connect();



// 部分路由器在省电模式下认证异常

esp_wifi_set_ps(WIFI_PS_NONE);



// 启动时清除损坏的射频校准（仅需在排查期使用，稳定后可移除）

esp_phy_erase_cal_data_in_nvs();

7.3 sdkconfig 注意事项

# N8R2 模组为 8MB Flash，勿配成 2MB

CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y



# 排查期可用全量校准

CONFIG_ESP_PHY_RF_CAL_FULL=y

7.4 CMakeLists.txt 依赖声明

ESP-IDF 中 main 组件一旦显式写了 REQUIRES，就不会自动继承默认依赖。若只写 REQUIRES esp_phy，会导致：

fatal error: esp_wifi.h: No such file or directory

正确写法：

idf_component_register(SRCS "station_example_main.c"

                    INCLUDE_DIRS "."

                    REQUIRES esp_wifi esp_netif esp_event nvs_flash esp_phy)

---

八、推荐排查流程（Checklist）

遇到「ESP32 WiFi 连不上但手机能连」时，建议按顺序执行：

第一步：确认配置链路

• menuconfig 中 SSID/密码正确

• 修改后执行了 idf.py build flash（而非仅 build）

• 串口最终打印的 SSID 与预期一致

第二步：读 reason 码

• 在断开事件中打印 reason

• 对照第四节速查表判断失败阶段

第三步：区分 RX 与 TX

• 连接前扫描：能否看到目标 AP？RSSI 多少？

• 能扫到但 reason=2 → 怀疑路由器端或 TX 射频

• 扫不到 → 怀疑 2.4G、SSID、天线

第四步：隔离路由器问题（关键）

• 用手机 2.4G 热点测试

• 换一台路由器测试

• 热点能连、原路由器不能 → 路由器问题

第五步：路由器侧操作

• 重启路由器

• 在管理页删除/踢掉 ESP 的 MAC 地址

• 检查最大连接数、AP 隔离、WPA3/PMF 强制

• 确认 2.4 GHz 已开启

第六步：硬件与供电

• USB 线直连主板，避免 Hub

• 必要时外接 5V 电源

• 检查天线连接（IPEX/板载）

---

九、经验总结

1. 「能扫描、连不上」≠ 密码错

扫描是被动接收，连接需要主动发包。失败阶段不同，原因完全不同。

2. menuconfig 配对了不代表不是软件问题，但也不一定不是路由器问题

本次配置自始至终正确，问题出在 AP 侧。

3. 「曾经连上过」是重要线索

指向会话残留、路由器状态变化，而非代码突变。

4. 换路由器是最快的定责手段

比反复改代码高效得多，应尽早做。

5. 务必打印 WiFi reason 码

官方示例默认不打印，排障成本会大幅上升。

6. ESP-IDF 的 REQUIRES 要写全

漏写 esp_wifi 会直接导致头文件找不到。

---

十、附录

A. 本项目最终成功配置

| 项目 | 值 |

|------|-----|

| 路由器 SSID | BEGLE_000539 |

| 加密 | WPA2-Personal |

| 频段 | 2.4 GHz / Channel 4 |

| ESP32 MAC | 28:37:2f:e5:73:18 |

| 分配 IP | 192.168.0.199 |

B. 常用命令

# 激活环境后

cd your_project

idf.py menuconfig          # 配置 WiFi

idf.py -p COM6 erase-flash flash monitor   # 全擦烧录（推荐排查时使用）

idf.py build               # 仅编译

C. 相关文件

• 示例代码：main/station_example_main.c

• WiFi 配置菜单：main/Kconfig.projbuild

• 编译产物配置：sdkconfig

---

文档基于 ESP-IDF v5.4 wifi/station 示例实战排障整理，适用于 ESP32 / ESP32-S3 系列 Station 模式连接问题参考。