ESP-IDF保姆级入门22｜WiFi联网与网络编程全解：STA/AP双模式/TCP-UDP Socket/HTTP服务端/自动重连，掌握工业级可靠网络通信

专栏前言

上一篇我们掌握了OTA空中升级体系 ，实现了远程固件迭代与故障自动回滚，解决了设备的远程运维问题。而这一切的基础，都是WiFi网络连接与数据通信。

对于物联网设备而言，网络是连接设备与云端的桥梁，从简单的联网上报，到复杂的远程控制、实时通信，都依赖稳定的网络连接与可靠的编程实现。

很多新手对WiFi网络的理解停留在"输入SSID密码连接就行"，但实际工程中需要处理：断网自动重连、弱网优化、TCP/UDP选型、服务端客户端设计、连接稳定性、网络安全等一系列问题。

ESP-IDF 提供了完整的WiFi驱动与LwIP轻量级TCP/IP协议栈，支持STA/AP双模式、标准Socket接口、多种应用层协议，从底层驱动到高层应用都有成熟的组件。

本篇一次性讲透ESP-IDF下的WiFi与网络编程：

STA/AP双模式原理 → WiFi事件驱动与自动重连 → TCP/UDP Socket编程 → HTTP客户端与服务端 → 网络可靠性优化 → 安全设计 → 最佳实践与踩坑汇总

全程配可编译源码+架构图解，零基础也能实现工业级稳定的网络通信。

---

一、WiFi核心基础与双模式

1. ESP32 WiFi架构

ESP32 集成了完整的WiFi MAC和基带，支持802.11 b/g/n标准，工作在2.4GHz频段。ESP-IDF在上层集成LwIP轻量级TCP/IP协议栈，提供标准BSD Socket编程接口，和Linux网络编程逻辑基本一致，上手门槛低。

整个网络从上到下分为五层：

• 应用层：HTTP、MQTT、WebSocket等业务协议
• 传输层：TCP、UDP传输协议
• 网络层：IP、ICMP、ARP协议
• 数据链路层：WiFi MAC驱动、802.11协议
• 物理层：WiFi射频、基带硬件

2. 两种基础工作模式

ESP32 WiFi主要分为两种基础模式，同时支持STA+AP共存模式：

• STA模式（站点模式）：设备作为终端连接到路由器，接入局域网和互联网，和手机、电脑连WiFi是同一个角色。这是最常用的模式，适用于绝大多数联网设备。
• AP模式（接入点模式）：设备自身作为热点，其他终端可以连接上来组成局域网。适用于无路由器场景、设备配网、本地直连控制。
• STA+AP共存模式：同时作为站点连接路由器，又作为热点允许其他设备接入，适用于中继、网关类设备。

3. 核心特性对比

特性	STA模式	AP模式
网络角色	终端设备	热点路由器
IP地址	由路由器DHCP分配	自身固定IP
联网能力	可访问互联网	仅局域网内部通信
连接数	连接1个路由器	支持多个终端同时接入
典型场景	普通联网设备、数据上报、OTA升级	设备配网、本地控制、无路由场景

【配图1：ESP32 WiFi双模式与网络分层架构图】

配图说明：左侧展示STA模式连接路由器接入互联网，右侧展示AP模式被终端连接，中间展示TCP/IP协议栈分层结构，直观呈现两种模式的角色与网络层级。

---

二、WiFi STA模式与自动重连

1. 事件驱动机制

ESP-IDF的WiFi采用事件驱动架构，连接状态变化、IP获取、断开等都会通过事件循环通知应用层，应用层通过注册事件回调处理对应事件，无需轮询状态，效率更高、响应更及时。

核心事件：

• WIFI_EVENT_STA_START：STA启动完成
• WIFI_EVENT_STA_CONNECTED：成功连接到路由器
• WIFI_EVENT_STA_DISCONNECTED：连接断开
• IP_EVENT_STA_GOT_IP：成功获取IP地址

2. 自动重连设计

工业级设备必须支持断网自动重连，网络恢复后自动重新连接，无需人工干预。ESP-IDF默认开启基础重连，工程中通常会增加重试次数、退避机制，避免频繁重试占用系统资源。

实战1：STA模式连接WiFi+自动重连

实现功能：配置WiFi参数，连接路由器，通过事件监听连接状态，断开后自动退避重试，获取IP后打印网络信息。

#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"

#define TAG "WIFI_STA"
#define WIFI_SSID "你的WiFi名称"
#define WIFI_PASSWORD "你的WiFi密码"
#define MAX_RETRY 10  // 最大重试次数

static uint8_t retry_cnt = 0;

// 事件回调函数
static void wifi_event_handler(void* arg, esp_event_base_t event_base,
                                int32_t event_id, void* event_data)
{
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
        ESP_LOGI(TAG, "WiFi启动，开始连接...");
        esp_wifi_connect();
    } 
    else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_CONNECTED) {
        ESP_LOGI(TAG, "WiFi连接成功");
        retry_cnt = 0;
    } 
    else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        if (retry_cnt < MAX_RETRY) {
            retry_cnt++;
            ESP_LOGW(TAG, "WiFi断开，第%d次重连...", retry_cnt);
            vTaskDelay(pdMS_TO_TICKS(2000)); // 2秒退避重试
            esp_wifi_connect();
        } else {
            ESP_LOGE(TAG, "重连次数超限，连接失败");
        }
    } 
    else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
        ESP_LOGI(TAG, "获取IP成功：" IPSTR, IP2STR(&event->ip_info.ip));
    }
}

// WiFi初始化
void wifi_sta_init(void)
{
    // 初始化网络接口与事件循环
    esp_netif_init();
    esp_event_loop_create_default();

    // 创建默认STA网络接口
    esp_netif_create_default_wifi_sta();

    // 初始化WiFi驱动
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    esp_wifi_init(&cfg);

    // 注册WiFi事件和IP事件回调
    esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL);
    esp_event_handler_register(IP_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL);

    // 配置WiFi参数
    wifi_config_t wifi_config = {
        .sta = {
            .ssid = WIFI_SSID,
            .password = WIFI_PASSWORD,
            .threshold.authmode = WIFI_AUTH_WPA2_PSK,
        },
    };

    esp_wifi_set_mode(WIFI_MODE_STA);
    esp_wifi_set_config(WIFI_IF_STA, &wifi_config);
    esp_wifi_start();
}

void app_main(void)
{
    nvs_flash_init();
    wifi_sta_init();
}

3. 关键说明

• 事件回调在事件循环任务中执行，不要在回调里做长时间阻塞操作，复杂逻辑应转到自定义任务中
• 退避重试可以避免网络故障时频繁重试加重网络负担，实际项目可采用指数退避策略
• 固定场景可配置静态IP，避免DHCP分配延迟，提升连接速度

---

三、Socket网络编程

WiFi连接成功后，就可以通过Socket接口进行网络数据传输。Socket是网络编程的标准接口，ESP-IDF基于LwIP实现了标准BSD Socket，跨平台兼容性强。

1. TCP与UDP对比

传输层最常用的两个协议，适用场景完全不同：

特性	TCP	UDP
连接特性	面向连接，三次握手建立链路	无连接，直接发送数据
可靠性	可靠传输，丢包自动重传，保证顺序	不可靠，不保证到达，不保证顺序
传输开销	头部开销大，传输效率低	头部开销小，传输效率高
流量控制	有滑动窗口、拥塞控制	无
典型场景	固件升级、HTTP、MQTT、关键数据上报	实时音视频、广播、快速控制指令

2. TCP客户端标准流程

创建Socket → 配置服务器地址 → 发起连接 → 循环收发数据 → 关闭连接。

实战2：TCP客户端数据收发

实现功能：连接指定TCP服务器，定时发送心跳数据，接收服务器返回的数据，异常断开自动退出。

#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"

#define TAG "TCP_CLIENT"
#define SERVER_IP "192.168.1.100"  // 服务器IP
#define SERVER_PORT 8080            // 服务器端口

void tcp_client_task(void *pvParameters)
{
    int sock = -1;
    struct sockaddr_in server_addr;
    char send_buf[128];
    char recv_buf[128];
    uint32_t cnt = 0;

    // 1. 创建TCP Socket
    sock = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (sock < 0) {
        ESP_LOGE(TAG, "创建Socket失败");
        vTaskDelete(NULL);
        return;
    }

    // 2. 配置服务器地址
    server_addr.sin_family = AF_INET;
    server_addr.sin_port = htons(SERVER_PORT); // 端口转网络字节序
    inet_pton(AF_INET, SERVER_IP, &server_addr.sin_addr);

    // 3. 连接服务器
    int ret = connect(sock, (struct sockaddr*)&server_addr, sizeof(server_addr));
    if (ret != 0) {
        ESP_LOGE(TAG, "连接服务器失败");
        close(sock);
        vTaskDelete(NULL);
        return;
    }
    ESP_LOGI(TAG, "连接服务器成功");

    // 4. 循环收发数据
    while (1) {
        snprintf(send_buf, sizeof(send_buf), "设备心跳，计数：%d", cnt++);
        // 发送数据
        send(sock, send_buf, strlen(send_buf), 0);
        ESP_LOGI(TAG, "发送：%s", send_buf);

        // 接收数据
        int len = recv(sock, recv_buf, sizeof(recv_buf)-1, 0);
        if (len > 0) {
            recv_buf[len] = '\0';
            ESP_LOGI(TAG, "收到：%s", recv_buf);
        } else if (len == 0) {
            ESP_LOGW(TAG, "服务器断开连接");
            break;
        } else {
            ESP_LOGE(TAG, "接收失败");
            break;
        }

        vTaskDelay(pdMS_TO_TICKS(2000));
    }

    // 5. 关闭Socket
    close(sock);
    vTaskDelete(NULL);
}

【配图2：TCP Socket通信流程与数据流向图】

配图说明：分别展示客户端和服务端的Socket调用流程，三次握手、数据传输、四次挥手的过程，标注数据流向与接口调用顺序，直观呈现TCP通信的完整流程。

---

四、进阶：HTTP与AP模式配网

1. HTTP客户端

HTTP是最常用的应用层协议，ESP-IDF提供了原生的esp_http_client组件，封装了HTTP请求、响应、重定向、超时、TLS加密等功能，比自行用Socket实现更简单可靠。

典型应用包括数据上报、固件升级、云端接口调用，之前的OTA升级底层就是基于HTTP客户端。

2. AP模式与Web配网

AP模式最常用的场景就是设备配网：设备首次启动进入AP模式，手机连接设备热点，通过网页向设备发送WiFi名称和密码，设备收到后保存参数并切换到STA模式连接路由器。

这是智能设备最通用的配网方式。

实战3：AP模式创建Web服务器配网

实现功能：启动AP热点，创建轻量Web服务器，接收浏览器提交的WiFi配置，保存到NVS后切换到STA模式。

#include <stdio.h>
#include <string.h>
#include "esp_wifi.h"
#include "esp_http_server.h"
#include "esp_log.h"
#include "nvs_flash.h"

#define TAG "AP_WEBCONFIG"
#define AP_SSID "ESP32_Config"
#define AP_PASS "12345678"

httpd_handle_t server = NULL;

// 主页处理函数
static esp_err_t index_handler(httpd_req_t *req)
{
    const char *html = "<html><body>"
        "<h1>WiFi配置</h1>"
        "<form method='POST' action='/save'>"
        "SSID:<input name='ssid'><br>"
        "密码:<input name='password' type='password'><br>"
        "<button type='submit'>保存</button>"
        "</form></body></html>";
    httpd_resp_send(req, html, strlen(html));
    return ESP_OK;
}

// 保存配置处理函数
static esp_err_t save_handler(httpd_req_t *req)
{
    char buf[128];
    int ret = httpd_req_recv(req, buf, sizeof(buf)-1);
    if (ret > 0) {
        buf[ret] = '\0';
        // 解析ssid和password，保存到NVS
        ESP_LOGI(TAG, "收到配置：%s", buf);
        // 保存完成后重启切换到STA模式
    }
    httpd_resp_send(req, "配置成功，即将重启", strlen("配置成功，即将重启"));
    return ESP_OK;
}

// 启动Web服务器
void start_webserver(void)
{
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
    httpd_start(&server, &config);

    httpd_uri_t index_uri = {
        .uri = "/",
        .method = HTTP_GET,
        .handler = index_handler,
    };
    httpd_register_uri_handler(server, &index_uri);

    httpd_uri_t save_uri = {
        .uri = "/save",
        .method = HTTP_POST,
        .handler = save_handler,
    };
    httpd_register_uri_handler(server, &save_uri);
}

// AP模式初始化
void wifi_ap_init(void)
{
    esp_netif_init();
    esp_event_loop_create_default();
    esp_netif_create_default_wifi_ap();

    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    esp_wifi_init(&cfg);

    wifi_config_t wifi_config = {
        .ap = {
            .ssid = AP_SSID,
            .password = AP_PASS,
            .max_connection = 4,
            .authmode = WIFI_AUTH_WPA2_PSK,
        },
    };

    esp_wifi_set_mode(WIFI_MODE_AP);
    esp_wifi_set_config(WIFI_IF_AP, &wifi_config);
    esp_wifi_start();
    ESP_LOGI(TAG, "AP模式启动，SSID：%s", AP_SSID);
}

【配图3：AP模式Web配网流程示意图】

配图说明：展示设备启动AP→手机连接热点→浏览器访问配置页面→提交WiFi参数→设备切换STA模式的完整流程，直观呈现配网的交互过程。

---

五、工程最佳实践

1. 连接可靠性设计

• 自动重连+退避机制：断网后采用指数退避重试，避免频繁重试，超过最大次数进入降级运行模式
• 心跳保活：长连接场景定时发送心跳包，检测链路是否断开，及时触发重连
• 状态监控：定时检测连接状态、信号强度、网络质量，异常提前预警并记录日志
• 多网络备份：网关类设备支持WiFi+有线、双WiFi备份，主网络故障自动切换

2. 性能优化

• TCP参数优化：根据场景调整发送接收缓冲区大小、滑动窗口、超时时间
• 数据批量传输：减少小包发送次数，批量合并发送，提升有效数据占比
• WiFi功耗优化：低速率场景开启WiFi休眠模式，降低发射功率
• 协议选型：小数据高实时用UDP，大数据可靠传输用TCP，消息通信优先用MQTT

3. 安全设计

• WiFi安全：使用WPA2/WPA3加密，禁止开放热点
• 传输安全：敏感数据使用HTTPS、TLS加密，禁止明文传输
• 身份认证：设备连接服务器需要身份校验，防止非法设备接入
• 端口防护：不使用的端口全部关闭，服务端增加访问控制策略

---

六、新手高频踩坑汇总

1. WiFi连接总是失败
   • SSID或密码错误，注意大小写和特殊字符
   • 路由器频段不支持，ESP32只支持2.4GHz，不支持5GHz
   • 加密模式不匹配，路由器设置了更高级的加密方式
   • 信号太弱，距离路由器过远或有遮挡
2. Socket连接成功但收不到数据
   • 端口号字节序错误，没有用htons转换网络字节序
   • 接收缓冲区设置太小，数据被截断
   • TCP粘包，没有处理分包逻辑，误以为一次接收就是完整数据包
   • 防火墙拦截，服务器端口没有开放
3. 网络不稳定、频繁断开
   • 没有自动重连机制，断开后无法自动恢复
   • WiFi信号弱、干扰大，丢包严重
   • 长连接没有心跳保活，被路由器超时断开
   • 任务栈太小，网络协议栈溢出导致异常
4. AP模式手机连不上
   • 密码长度不够，WPA2密码至少8位
   • 信道冲突，周围热点太多干扰大
   • 连接数超过最大值，ESP32 AP默认最多4个连接
5. HTTP请求失败
   • 域名解析失败，没有配置DNS服务器
   • 证书问题，HTTPS服务器证书不被信任
   • 请求格式错误，头部不完整

---

下一篇预告（23篇）

ESP-IDF保姆级入门23｜MQTT物联网通信全解：MQTT协议原理、QoS服务质量、主题订阅发布、遗嘱消息、EMQX对接、工业级通信可靠性设计，掌握物联网设备的标准消息通信方案，实现设备与云端的高效数据交互！