ESP-IDF v6.1：SoftAP 配网在干什么（手机连开发板热点）

文章目录

[ESP-IDF v6.1：SoftAP 配网在干什么（手机连开发板热点）](#ESP-IDF v6.1：SoftAP 配网在干什么（手机连开发板热点）)
- 一、验收目标
- [二、SoftAP 配网在现象上是什么](#二、SoftAP 配网在现象上是什么)
- 三、烧录前请先满足
- 四、操作顺序（按这个走）
- - [4.1 手机连 SoftAP](#4.1 手机连 SoftAP)
  - [4.2 打开配网页](#4.2 打开配网页)
  - [4.3 扫描并保存家用 Wi‑Fi](#4.3 扫描并保存家用 Wi‑Fi)
  - [4.4 手机改回家里网，用 STA IP 访问](#4.4 手机改回家里网，用 STA IP 访问)
- 五、两种打开设备页的方式（对照）
- [六、与文 00～03 的分工](#六、与文 00～03 的分工)
- 七、验收清单
- 八、常见问题
- 九、小结
- 系列博文

ESP-IDF v6.1：SoftAP 配网在干什么（手机连开发板热点）

级别： 实战篇（免费）

适合谁读： 已按本系列把 ESP32-S3 环境装好，并能烧录 hello_world；准备把板子连上家里 Wi‑Fi 的读者。

适用： Windows 10/11；ESP-IDF v6.1 ；乐鑫 ESP32-S3-DevKitC-1 ；演示工程以能开 SoftAP 网页的练兵工程为准（文中称 wifi_led）。

目标： 理解 SoftAP 配网时「手机看到什么、浏览器打开什么、配完后怎么换回家用网」；能按步骤完成一次配网验收。
上一篇（工程路径 / set-target）：ESP-IDF v6.1：工程路径规范、set-target 与 sdkconfig

COM 口烧录：找到 COM 口，把 hello_world 烧进去

Flash 配错重启：Flash 配置容量与实物不一致

环境安装：Windows 上从零搭 ESP-IDF

本文只讲 SoftAP 配网的现象与操作顺序。不讲网页控灯细节（下一篇）、不讲 MQTT 上云、不展开 Wi‑Fi 状态机与完整源码。

摘要： SoftAP 模式下开发板会发出一个 Wi‑Fi 热点；手机连上该热点后，用浏览器打开设备页（常见 http://192.168.4.1/），扫描并填写家用 Wi‑Fi，让板子以 STA 身份入网。配通后手机应改回连路由器，再用板子的局域网 IP 访问页面。

关于演示工程 wifi_led： 这是本系列练兵用的自研演示固件名称（SoftAP + 设备网页 + 后续控灯等）。本文不附完整工程包 （平台核心实现不随文公开）。若你手上只有官方 hello_world，仍可先读懂 SoftAP 配网顺序；要实机跟做本节验收，需要一份已具备 SoftAP + HTTP 设备页 的固件（组件上通常会用到 esp_http_server）。网页开灯/关灯的操作验收见下一篇；工程是否另开源、以何处为准，以作者后续文末或评论区说明为准。

一、验收目标

同时满足即通过：

串口日志里能看到 SoftAP 的 SSID（形如 WIFI-LED-xxxx）与配网页地址提示
手机能搜索并连上该 SoftAP（演示默认密码下文给出）
浏览器能打开配网页（常见为 http://192.168.4.1/）
在页面上完成「扫描 → 选家用 SSID → 填密码 → 保存连接」
板子拿到 STA IP 后，手机改回自家 Wi‑Fi，仍能用该 IP 打开设备页

二、SoftAP 配网在现象上是什么

可以把 SoftAP 理解成：开发板临时当「小路由器」，专门方便你第一次（或换网时）把家用 Wi‑Fi 账号告诉它。

角色	配网时在做什么
开发板 SoftAP	发出热点；网页地址常见为 `http://192.168.4.1/`（见下说明）
手机	先连板子热点，打开网页填家用 Wi‑Fi
开发板 STA	用你填的账号去连路由器，拿到局域网 IP
手机（配完后）	改回连家里路由器，再用 STA IP 访问板子

ESP-IDF 支持 STA （连路由器）、AP （当热点）、APSTA （两者共存）等模式。很多产品固件使用 AP+STA 共存（APSTA） ：板子一边作为 STA 连接路由器，一边持续保留 SoftAP，随时可再连配网页重配。也有另一种常见设计：配网成功后关闭 AP，只保留 STA 。两种都常见，取决于固件逻辑------不要默认「配完热点一定会消失」。

本文演示侧属于「配通后 SoftAP 往往还在」这一类；若你的固件配完热点消失，只要 STA IP 能打开页面，同样算配网成功。公开文只需记住操作现象：配网阶段靠 SoftAP 网页；日常访问多用 STA IP。

关于 192.168.4.1：这是 ESP-IDF SoftAP 很常见的默认网关地址 （DHCP 也常落在同网段），但不是硬件写死的唯一可能；具体以你固件/网络接口配置及串口提示为准。

官方 Wi‑Fi 驱动概览：https://docs.espressif.com/projects/esp-idf/zh_CN/v6.1/esp32s3/api-guides/wifi.html

三、烧录前请先满足

项	说明
环境与 COM	文 00 / 02：能 `flash` / `monitor`
Flash 容量	文 01：实板常见 8MB，勿配成 16MB 导致重启
工程能力	固件需能开 SoftAP，并提供配网页（HTTP）。自研演示工程路径示例：`F:\esp\projects\wifi_led`。若你从零拼组件，需确保已启用 HTTP Server（`menuconfig` → Component config → HTTP Server / `esp_http_server`）；本文不展开页面与配网业务代码
手机	能连 2.4GHz Wi‑Fi（ESP32-S3 不支持 5GHz）。家用路由若开了「智能带导」等，必要时先关，减少扫描不到的情况

激活 IDF 环境（PowerShell）。EIM（Espressif IDF Manager） 是乐鑫官方的 IDF 安装/管理工具；下文 profile 路径以 EIM 实际安装位置为准，可在 EIM 仪表板查看：

powershell 复制代码

. 'C:\Espressif\tools\Microsoft.v6.1.PowerShell_profile.ps1'
idf.py --version

确认输出为 v6.1.x。CMD 用户请使用 EIM 生成的「ESP-IDF CMD」，不要把 PowerShell 脚本贴进 CMD。

烧录与监视（把 COMx 换成设备管理器里的真实端口）：

powershell 复制代码

cd F:\esp\projects\wifi_led
idf.py -p COMx flash monitor

启动正常时，串口日志形态可对照下面这类示例（TAG / 时间戳因工程而异，看关键词即可）：

text 复制代码

I (1234) net: SoftAP SSID=WIFI-LED-A2B4 PASS=12345678  → http://192.168.4.1/
I (1300) http: HTTP server on :80
...（配网保存并连接成功后）...
I (5600) net: STA got IP:192.168.1.47

若仍循环重启，先按文 01 核对 Flash，不要先怀疑「配网网页写坏了」。

说明：SSID 后缀、默认密码、日志 TAG 以你烧进去的那份固件为准；上文为便于对照的示意。

四、操作顺序（按这个走）

4.1 手机连 SoftAP

打开手机 Wi‑Fi 列表
找到形如 WIFI-LED-xxxx 的热点（xxxx 以串口为准）
密码按串口提示填写（演示常见：12345678）
连上后，部分手机会提示「当前网络无互联网」------配网阶段正常

重要（高频坑）： 部分手机（尤其 iOS ）检测到 SoftAP 无互联网时，会弹出「无法访问互联网」，甚至自动切回自家 Wi‑Fi / 移动数据 。配网阶段请先不要急着点「使用蜂窝数据」或切走网络，手动保持连在该热点上。部分安卓机需在 Wi‑Fi 设置中关闭「智能网络切换」「自动切换移动数据」等类似选项，否则会出现「连上就断、网页打不开」。

4.2 打开配网页

建议用手输地址，并使用 Chrome / Edge 等浏览器，尽量不要依赖系统 Wi‑Fi「登录门户」弹窗里的内置页。在地址栏输入：

text 复制代码

http://192.168.4.1/

能打开设备页（有状态区、配网区）即过关。打不开时见第八节。

先确认：

手机仍连着该 SoftAP
地址仍是 http:// ，没有被浏览器自动改成 https://（内网 HTTP 被强制 HTTPS 时经常打不开）
没有被自动加上 www.（例如错误成 https://www.192.168.4.1）

Captive portal（强制门户）劫持： 连上 SoftAP 后，有的手机会直接弹出运营商/路由器「登录页」，或把你带到无关门户。对策：关掉弹窗，打开 Chrome/Edge，手动输入 http://192.168.4.1/。

4.3 扫描并保存家用 Wi‑Fi

页面上的配网区通常是这类顺序（文案以你固件页面为准）：

点 「扫描附近 Wi‑Fi」（或同等按钮）
在列表里选中你家 2.4GHz SSID（或按页面说明手输 SSID）。5GHz 网络 ESP32-S3 搜不到，必须选 2.4GHz
填入 Wi‑Fi 密码
点 「保存并连接」（或同等按钮）

双频同名（2.4G/5G 合一）： 扫描列表里可能只看到一条 SSID。板子实际只能上 2.4G；部分路由又爱把手机往 5G 导。排查不稳时，稳妥做法是在路由器里临时拆开：给 2.4G 单独一个 SSID 再测。

串口成功后常见类似 STA got IP: 192.168.x.x。把这个 IP 记下来。

4.4 手机改回家里网，用 STA IP 访问

手机 Wi‑Fi 离开 WIFI-LED-xxxx，改连你家路由器
确认手机与开发板在同一局域网
浏览器打开：http://<STA_IP>/（例如 http://192.168.1.11/）

能再次打开设备页，即完成本文 SoftAP 配网验收。网页上的开灯/关灯留给下一篇专门验收。

五、两种打开设备页的方式（对照）

方式	何时用	手机连谁	浏览器地址
SoftAP	第一次配网、换路由器、忘记 STA IP	板子热点 `WIFI-LED-xxxx`	常见 `http://192.168.4.1/`（默认网段，以固件为准）
STA	日常使用	家里路由器	`http://<板子的局域网IP>/`

若固件是 APSTA 共存：配通后 SoftAP 往往还在，可再进配网页重配。若固件配完关 AP：日常只用 STA IP。两种都正常。

六、与文 00～03 的分工

篇	解决的问题
00	安装 IDF、选板、约定工程根目录
01	Flash 容量配错导致重启
02	COM / 线 / 驱动 + hello_world 烧录监视
03	工程路径、`set-target`、`sdkconfig` 与 defaults
04（本文）	SoftAP 配网现象：连热点 → 打开配网页 → 填家用 Wi‑Fi → 改用 STA IP

下一篇预告：局域网网页控灯实机走一遍（开灯/关灯验收）------链接待该篇发布后补充。

七、验收清单

（阅读时可自行勾选；部分客户端可能不渲染勾选框，发布后可将已完成项改为 [x]。）

monitor 中能看到 SoftAP SSID 与配网页提示
手机能连上 SoftAP，且配网过程中未被自动切走
浏览器能打开配网页（常见 http://192.168.4.1/，或以串口为准）
完成扫描/选网/保存连接（所选为 2.4GHz）
串口出现 STA IP
手机改回家里 Wi‑Fi 后，仍可用 STA IP 打开设备页

八、常见问题

现象	优先检查
手机搜不到 SoftAP	板子是否已正常启动（非 Flash 重启循环）？是否离板太远？列表刷新慢可多等几秒。若反复搜不到，检查 SoftAP 信道是否固定（常见 1 / 6 / 11；自动信道时有的手机更不稳定）
连上 SoftAP 马上断开 / 自动回家里网	见 §4.1：关掉智能切换；iOS 保持在该热点上，勿点用蜂窝数据替代
一连 SoftAP 就弹出运营商/路由器登录页	Captive portal 劫持：关弹窗，用 Chrome/Edge 手输 `http://192.168.4.1/`
能连 SoftAP 但打不开配网页	是否仍连着该热点？是否被改成 https 或加了 `www.`？试关私人 DNS / 代理；换浏览器
扫描列表为空或没有自家 SSID	是否在找 5GHz ？只要 2.4GHz；双频同名时临时拆开 2.4G SSID 再测
保存后一直连不上家用网	密码是否正确？是否选成访客网/隔离网？串口是否仍在重试
已拿到 STA IP，手机却打不开	手机是否已改回家里 Wi‑Fi？是否同网段？路由器是否开了「AP 隔离」
配通后 SoftAP 还在 / 已消失	还在：常见于 APSTA 共存。消失：常见于「配完关 AP」。以能打开 STA 页为准

九、小结

SoftAP 配网的核心现象是：手机先连板子热点，在网页里把家用 Wi‑Fi 交给板子。
配网页地址以串口为准；演示里最常见的是 http://192.168.4.1/（默认常见，非唯一强制）。
配通后手机要回到家里路由器，再用板子的 STA IP 打开页面。
注意：自动切网、captive portal、强制 HTTPS、2.4GHz、双频同名。
APSTA 共存与「配完关 AP」都常见，不要和「配网失败」混为一谈。
启动异常优先排除 Flash 容量等问题（文 01），再查配网步骤。

官方参考（ESP-IDF v6.1）：

Wi‑Fi 驱动程序：https://docs.espressif.com/projects/esp-idf/zh_CN/v6.1/esp32s3/api-guides/wifi.html

我们准备基于 ESP 开发板做一些实用的小产品，欢迎对照实践，并在评论区交流。

ESP-IDF v6.1：SoftAP 配网在干什么（手机连开发板热点）

文章目录