手把手教你用ESP32搭建一个稳定的TCP服务器
你有没有遇到过这样的场景：手里的传感器数据已经准备好了，但不知道怎么把它们“送出去”？想做个远程控制的小灯，却发现手机连不上开发板？其实，问题的关键不在于硬件，而在于通信。
在物联网的世界里，TCP协议就是设备与外界对话的“通用语言”。而ESP32，作为目前最热门的IoT芯片之一，天生就具备Wi-Fi能力——这意味着它不仅能“说话”，还能接入局域网，让任何在同一网络下的设备（比如你的手机、电脑）都能听懂它。
今天，我就带你从零开始，一步步搭建一个运行在ESP32上的TCP服务器。整个过程不需要复杂的工具，代码清晰可复用，还会告诉你那些官方文档不会明说的“坑”。
为什么是TCP？而不是UDP或其他？
在动手之前，先搞清楚一个问题：为什么选TCP？
简单来说：
-TCP是可靠的：发出去的数据包如果丢了，会自动重传。
-它是面向连接的：通信前必须建立“握手”，保证双方都在线。
-有顺序保障：数据按发送顺序到达，不会乱序。
这三点决定了它特别适合用于：
- 远程调试终端
- 工业传感器上报
- 智能家居中的指令交互
相比之下，UDP虽然快，但“说了就走”，不适合对稳定性要求高的场景。
所以，如果你希望设备和客户端之间的通信稳定、可控、可追溯，那TCP是首选。
整体架构：ESP32如何成为一台“迷你服务器”？
想象一下，你的ESP32其实可以像一台小型Web服务器一样工作。它的角色如下：
[PC / 手机 App] ↓ (通过Wi-Fi) [路由器] —— 分配IP给ESP32 ↓ [ESP32 TCP Server] ↓ [处理传感器/执行动作]关键点在于：
1. ESP32以Station模式连接到路由器，获取一个内网IP（如192.168.1.105）
2. 启动一个TCP服务，监听某个端口（比如8080）
3. 客户端通过192.168.1.105:8080发起连接请求
4. 建立连接后，双向通信就开始了
整个流程看似复杂，但在ESP-IDF框架下，已经被封装得非常简洁。
第一步：让ESP32连上Wi-Fi
没有网络，一切免谈。所以我们首先要让它成功接入Wi-Fi。
核心逻辑拆解
void wifi_init_sta(void) { tcpip_adapter_init(); ESP_ERROR_CHECK(esp_event_loop_create_default()); wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_wifi_init(&cfg)); // 注册事件回调 ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, wifi_event_handler, NULL)); ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, wifi_event_handler, NULL)); wifi_config_t wifi_config = { .sta = { .ssid = "your_ssid", .password = "your_password", .threshold.authmode = WIFI_AUTH_WPA2_PSK, }, }; ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config)); ESP_ERROR_CHECK(esp_wifi_start()); ESP_LOGI("WIFI", "正在连接Wi-Fi..."); }这段代码干了五件事：
1. 初始化TCP/IP协议栈（LWIP）
2. 创建事件循环，用于响应Wi-Fi状态变化
3. 设置Wi-Fi为STA模式（即客户端模式）
4. 配置要连接的SSID和密码
5. 启动Wi-Fi并开始尝试连接
⚠️ 注意：
tcpip_adapter_init()在新版本ESP-IDF中已被弃用，请使用ESP_NETIF_INIT_DEFAULT_WIFI_STA()替代。本文为兼容性保留原写法，实际项目建议更新。
关键事件处理：什么时候启动服务器？
很多人忽略了一个细节：不能一上电就启动TCP服务！
必须等Wi-Fi连接成功、拿到IP地址之后才行。否则你会看到一堆“bind失败”或“无法创建socket”的错误。
这就是事件回调函数的作用：
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_wifi_connect(); // 开始连接AP } 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("WIFI", "已连接，IP地址: " IPSTR, IP2STR(&event->ip_info.ip)); // ✅ 此时才安全地创建TCP服务器任务 xTaskCreate(tcp_server_task, "tcp_server", 4096, NULL, 6, NULL); } }只有当收到IP_EVENT_STA_GOT_IP事件时，才说明网络已就绪，此时再启动TCP服务器才是稳妥的做法。
第二步：构建TCP服务器核心逻辑
现在网络通了，接下来就是重头戏：如何让ESP32成为一个真正的TCP服务器？
Socket编程四步曲
在嵌入式系统中实现TCP服务器，本质上就是标准的Socket编程流程：
| 步骤 | 函数 | 作用 |
|---|---|---|
| 1. 创建套接字 | socket() | 获取通信句柄 |
| 2. 绑定地址端口 | bind() | 指定监听哪个IP和端口 |
| 3. 开始监听 | listen() | 等待客户端连接 |
| 4. 接受连接 | accept() | 建立实际通信通道 |
我们来看完整实现：
static void tcp_server_task(void *pvParameters) { char rx_buffer[128]; struct sockaddr_in server_addr, client_addr; socklen_t addr_len = sizeof(client_addr); int server_sock, client_sock; // 1. 创建TCP socket server_sock = socket(AF_INET, SOCK_STREAM, 0); if (server_sock < 0) { ESP_LOGE("TCP", "无法创建socket"); vTaskDelete(NULL); return; } // 2. 配置服务器地址 server_addr.sin_family = AF_INET; server_addr.sin_port = htons(SERVER_PORT); // 端口8080 server_addr.sin_addr.s_addr = htonl(INADDR_ANY); // 监听所有网卡 // 3. 绑定 if (bind(server_sock, (struct sockaddr *)&server_addr, sizeof(server_addr)) != 0) { ESP_LOGE("TCP", "绑定失败"); closesocket(server_sock); vTaskDelete(NULL); return; } // 4. 监听（最多允许4个等待连接） if (listen(server_sock, MAX_CLIENTS) != 0) { ESP_LOGE("TCP", "监听失败"); closesocket(server_sock); vTaskDelete(NULL); return; } ESP_LOGI("TCP", "TCP服务器启动，监听端口 %d", SERVER_PORT); while (1) { // 阻塞等待客户端连接 client_sock = accept(server_sock, (struct sockaddr *)&client_addr, &addr_len); if (client_sock < 0) { ESP_LOGW("TCP", "接受连接失败"); continue; } ESP_LOGI("TCP", "客户端已连接: %s:%d", inet_ntoa(client_addr.sin_addr), ntohs(client_addr.sin_port)); // 数据交互循环 while (1) { int len = recv(client_sock, rx_buffer, sizeof(rx_buffer) - 1, 0); if (len > 0) { rx_buffer[len] = '\0'; ESP_LOGI("TCP", "收到数据: %s", rx_buffer); send(client_sock, rx_buffer, len, 0); // 回显 } else { ESP_LOGI("TCP", "客户端断开连接"); break; } } closesocket(client_sock); } closesocket(server_sock); vTaskDelete(NULL); }关键点解析
📍INADDR_ANY是什么？
它表示监听本机所有可用的IP地址。即使ESP32只有一个Wi-Fi接口，也推荐使用这个宏，避免硬编码IP导致移植问题。
📍 缓冲区大小设多少合适？
这里用了128字节，适用于命令类短消息（如“ON”、“OFF”）。如果你要传输JSON或图片缩略图，建议提升到512甚至1024，并考虑分包机制。
📍 为什么用阻塞式recv()？
对于大多数轻量级应用，阻塞方式足够且更节省CPU资源。若需同时处理多个客户端或非阻塞操作，应结合FreeRTOS任务分离或使用select()机制。
实战技巧：避开新手常踩的五个坑
别急着烧录代码，先看看这些血泪经验总结出来的避坑指南：
❌ 坑1：IP变了找不到设备？
现象：每次重启ESP32，IP都不同，客户端连不上。
✅ 解决方案：
- 串口打印当前IP（已在代码中实现）
- 或配置路由器DHCP静态分配，固定ESP32的IP
- 更高级玩法：启用mDNS（.local域名），例如esp32-tcp.local
❌ 坑2：只能连一个客户端？
现象：第二个设备一连，第一个就被踢掉。
✅ 解决方案：
将每个客户端连接交给独立的任务处理：
xTaskCreate(client_handler_task, "client_handler", 4096, (void*)client_sock, 6, NULL);这样就能真正实现多客户端并发。
❌ 坑3：长时间运行后死机？
现象：运行几小时后程序卡住，ping不通。
✅ 可能原因：
- 内存泄漏（频繁创建/销毁任务未释放）
- TCP连接未正确关闭
- LWIP内存池耗尽
✅ 建议：
- 使用heap_caps_get_free_size(MALLOC_CAP_8BIT)定期监控内存
- 启用PSRAM（如有）扩展堆空间
- 添加看门狗定时器（Watchdog Timer）
❌ 坑4：防火墙阻止连接？
现象：ESP32显示“客户端已连接”，但PC收不到数据。
✅ 检查项：
- Windows防火墙是否放行该端口
- 手机App是否有网络权限
- 路由器是否开启AP隔离（客户端之间无法互访）
❌ 坑5：端口被占用？
现象：提示“bind failed: EADDRINUSE”
✅ 解决办法：
换一个端口号！推荐使用8080,9000,10000+的私有端口，避开HTTP（80）、HTTPS（443）等常用端口。
应用拓展：不只是回声服务器
你现在拥有的是一个基础TCP服务器模板。但它能做的远不止“你说啥我回啥”。
✅ 场景1：远程读取温湿度
客户端发送"GET_TEMP"→ ESP32返回"TEMP:23.5"
✅ 场景2：智能灯控制
客户端发送"LIGHT_ON"→ GPIO置高点亮LED
✅ 场景3：固件升级入口
客户端上传新固件bin文件 → ESP32进入OTA更新流程
只需要在recv()之后加个判断：
if (strcmp(rx_buffer, "GET_TEMP") == 0) { float temp = read_dht11(); sprintf(response, "TEMP:%.1f\r\n", temp); send(client_sock, response, strlen(response), 0); } else if (strcmp(rx_buffer, "LIGHT_ON") == 0) { gpio_set_level(LED_PIN, 1); send(client_sock, "OK", 2, 0); }是不是瞬间就有了产品雏形？
性能与优化建议
虽然ESP32性能强劲，但在做网络服务时仍需注意资源管理：
| 项目 | 建议 |
|---|---|
| 任务栈大小 | 至少2KB以上，推荐4KB（4096） |
| 最大并发数 | 不超过5个客户端（受限于内存） |
| 日志级别 | 生产环境关闭ESP_LOGD，减少串口干扰 |
| 心跳机制 | 客户端定期发送PING，防止假连接 |
| 超时设置 | recv()可配合setsockopt()设置接收超时 |
此外，生产环境中务必加入身份验证机制，比如Token校验，防止恶意连接耗尽资源。
最后一公里：测试你的服务器
写完代码只是第一步，验证才是关键。
方法1：用电脑命令行测试（Windows/Linux/macOS）
打开终端，输入：
telnet 192.168.1.105 8080（请替换成你ESP32的实际IP）
连接成功后，随便敲几个字符，你应该能在串口看到日志输出，并且收到回显。
方法2：用网络调试助手（推荐）
下载一款图形化工具，比如：
- NetAssist（Windows）
- TCP Client for Android/iOS
- Hercules Terminal
输入IP和端口，点击“Connect”，然后发送文本即可。
当你看到屏幕上跳出“客户端已连接”那一刻，你就已经跨过了物联网通信的第一道门槛。
下一步，你可以把它封装成API接口、加上JSON格式、对接MQTT网关……甚至做成一个完整的智能家居中枢。
而这一切，都是从这个小小的TCP服务器开始的。
如果你正在做一个esp32项目，不妨试试加上这个功能。你会发现，让设备“开口说话”，并没有想象中那么难。
项目源码已整理成GitHub模板，欢迎Star： github.com/example/esp32-tcp-server
有问题？欢迎在评论区留言讨论！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
