Windows原生移植LWIP：基于CMake与MinGW-W64的完整构建指南

做嵌入式网络开发的朋友，十有八九都跟 LWIP 协议栈打过交道。这个轻量级 TCP/IP 协议栈在 Flash 和 RAM 占用上极其克制，却在 STM32、GD32、ESP32 这些平台上扛起了大量网络功能，算得上是嵌入式网络生态里的硬核“钉子户”。但我今天不想聊单片机上的标准流程——CubeMX 生成、Keil 编译、下载跑通就完事——而是想聊聊另一个经常被忽略的场景：在 Windows 上原生移植 LWIP，并且用 CMake 搭配 MinGW-W64 工具链来构建。

之所以会写这篇文章，是因为我最近在做一套上位机网络模拟测试环境，需要把协议栈跑在 PC 上验证应用层逻辑。原以为把 LWIP 源码拖下来、CMake 一配就能跑，结果前前后后踩了不下十几个坑，光工具链就重装了三遍。这篇文章把完整的踩坑记录和最终可行的配置方案整理出来，适合那些想绕开厂商 SDK、把 LWIP 从“板子限定”里解放出来的开发者参考。不论你是想搞自动测试、协议二次开发，还是单纯想在 PC 上把 lwip 代码调通，这套思路都能帮你少走很多弯路。

1. 项目缘起与方案选型

1.1 为什么要在 Windows 上跑 LWIP

先把场景说清楚。很多嵌入式项目的网络逻辑其实分两层：底层的 lwip 协议栈，以及上层的应用协议（MQTT、HTTP Client、自定义报文等）。平时在单片机上开发，最头疼的就是调试手段太有限，日志接口要自己抠、打印也不能随便开，断点打多了还影响实时性。遇到一个疑似协议栈初始化顺序的问题，光是加打印重编烧录，就能耗掉半天。

把 LWIP 搬到 Windows 上之后，情况一下就好转了。你可以在 Visual Studio Code 里直接打断点，用 Wireshark 抓本机回环包，甚至写脚本去模拟对端设备。最方便的是编译速度快，改一个宏定义几秒钟就能重新构建，完全不用碰烧录器。尤其是要验证 TCP 状态机、重传逻辑、超时处理这类时间敏感的功能，PC 上的调试体验比 MCU 舒服太多。

还有一个容易被忽视的用途：作为自动化测试框架的底层。你可以用 CMake 把 lwip 编译成静态库，再包装成一套虚拟网卡接口，让测试程序直接调用 socket API 或者 netconn API。这样就能在 CI 环境里自动跑协议一致性测试，不用每次都在真实硬件上验证。我这次的项目本质上就是干这个。

1.2 为什么选 CMake 和 MinGW-W64 而不是其他方案

在 Windows 上编译 LWIP，其实有好几条路。最省事的当然是 MSYS2 的完整 Unix 模拟环境，但它有个问题：编译出来的程序依赖 POSIX 层，行为跟真实 Windows 原生程序有差异，而且很多嵌入式里用到的 GCC 扩展特性在模拟层里表现也不完全一致。MSVC 就更麻烦，lwip 源码里有些地方依赖 GCC 的 _Pragma 和字节序处理，用 MSVC 编译虽然能做，但需要改的地方比想象中多。

所以我的选择是 MinGW-W64。理由很直接：第一，它是真正的 Windows 原生工具链，不依赖模拟层；第二，它的编译器是 GCC，和嵌入式交叉编译环境（arm-none-eabi-gcc）行为最接近，脑细胞能省不少；第三，它的链接和编译参数风格跟 Linux 下几乎一模一样，后期如果想把这套代码迁到 Linux 服务器上跑，基本只需要改 CMakeLists.txt 里的平台判断。

CMake 则是绑定选项，没有悬念。lwip 本身的源代码完全跨平台，真正麻烦的是构建脚本。用 Makefile 写的话，Windows 和 Linux 两套要维护；用 CMake 写一套，两个平台通吃。而且 CMake 对 MinGW-W64 的支持在 3.20 版本之后已经很成熟了，生成器直接选 "MinGW Makefiles" 就能跑，没有必要再引入 Ninja 增加复杂度。

2. 环境准备：工具链安装与验证

2.1 CMake 安装避坑

CMake 的安装本身很简单，去官网下载 Windows x64 安装包，一路 Next 就行。真正容易翻车的点是安装时有一个选项叫 "Add CMake to the system PATH for all users"，很多人不勾，装完在命令行敲cmake --version提示找不到命令，然后就开始怀疑人生。

我建议安装时直接勾上这个选项，省得后面手动配环境变量。如果你已经装好了，也可以手动把 CMake 的 bin 目录加到系统 PATH 里，比如C:\Program Files\CMake\bin。验证是否成功，打开新的终端窗口，输入cmake --version，看到版本号输出就说明没问题。

这里有个细节：CMake 版本别太老。太老的版本对 MinGW-W64 的支持不完整，可能出现生成的 Makefile 里包含错误命令的情况。我实测下来，3.20 以上的版本都靠谱，用新版其实无所谓，直接去官网下载当前最新的稳定版即可。另外，如果你在 PowerShell 里敲cmake提示 “无法将 cmake 项识别为 cmdlet” 之类的错误，八成就是 PATH 没生效，先检查环境变量，然后关掉终端重新开一个。

2.2 MinGW-W64 安装的三种方式

这里要说重点了。MinGW-W64 的安装比 CMake 复杂，因为它的发行版很多，而且很容易装上 EOL（End of Life）的旧版本。我踩过最大的坑就是从 SourceForge 上下的安装器，装完之后 gcc 版本还是 8.1.0，很多新代码编译不过。后来搞清楚原因了：SourceForge 上那个官方安装器默认拉取的是非常古老的构建，你要是图省事用它，后面编译 lwip 时遇到各种奇怪的语法错误，别急着怀疑代码，先查查编译器版本。

我的推荐方案有两个。

方案一，用 MSYS2。这个方法最干净。去 msys2.org 下载安装器，装完后在 MSYS2 终端里执行：

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja

然后用 MSYS2 自带的终端，把C:\msys64\mingw64\bin这个目录加到 Windows 的 PATH 里。注意，是mingw64\bin，不是 MSYS2 根目录下的usr\bin。后者是 Unix 工具链，混用会出问题。

方案二，用 winlibs.com 的预编译包。这个网站会持续更新 MinGW-W64 的构建，直接下载对应位数和线程模型（推荐win64和posix）的压缩包，解压到你喜欢的位置，然后把解压目录里的mingw64\bin加到 PATH 即可。

我个人的实际使用感受是，winlibs 的包更省心，不需要装 MSYS2 那一整套。但 MSYS2 的好处在于后续想装别的库方便，两条路都行，看你的习惯。装完验证一下：

gcc --version mingw32-make --version

注意，MinGW-W64 自带的 make 叫mingw32-make，不是make。如果你敲make提示找不到，是正常的，别慌。

2.3 环境变量配置与完整验证

工具链装完后，PATH 里应该同时包含 CMake 的 bin 目录和 MinGW-W64 的 bin 目录。我在 Windows 11 上做个完整的验证流程，建议你照做一遍：

# 检查 CMake cmake --version # 检查编译器 gcc --version # 检查 make mingw32-make --version # 编译一个最简单的 hello world 验证 echo '#include <stdio.h>' > test.c echo 'int main(){printf("hello\n");return 0;}' >> test.c gcc test.c -o test.exe ./test.exe

如果最后一步能输出 hello，说明 GCC 和 PATH 都正常。这里有个容易忽略的小坑：加完 PATH 后，如果你用的是 VSCode，必须重启 VSCode，不然终端里不会加载新的环境变量。如果你用的是 Windows Terminal，关掉所有标签页再重新打开，或者直接右键以管理员身份重开一个。

还有一个很隐蔽的问题：如果系统里同时安装了别的 GNU 工具链（比如 Git 自带的 bash 环境），PATH 顺序会影响你用哪个编译器。建议在验证时用which gcc或者where gcc看看是不是指向了你想要的那个mingw64\bin路径。如果指向了别的地方，把 MinGW-W64 的路径挪到 PATH 最前面即可。

3. LWIP 源码结构与移植前置准备

3.1 源码获取：从 GitHub 拉取 lwip 和 contrib

LWIP 的源码托管在 GitHub 上，主仓库是lwIP组织下的lwip，稳定版标记为STABLE-2.2.0（现在也有更新的版本了，看你的需求）。除了主仓库，强烈建议把contrib仓库也拉下来，里面包含了各种操作系统移植层、示例应用、测试代码，对理解移植要点非常有帮助。

git clone -b STABLE-2.2.0 https://github.com/lwIP-tcpip/lwip.git git clone https://github.com/lwIP-tcpip/contrib.git

如果没有 Git，也可以直接在 GitHub 页面上下载 zip 包。不过我还是建议学一下 Git，哪怕是多花半小时。记住这次移植用的 API 版本，后面配置宏定义时要用。lwIP 2.x 系列内部 API 变化较大，很多网上教程都是 1.4.x 时代的产物，照着抄会出大问题。

获取源码后，先看一下目录结构。src/下面有五个核心目录：

• core/：协议栈核心，TCP/IP 实现都在这里。
• api/：netconn 和 socket API 的实现。
• netif/：网络接口层，包含 etharp、ethernet 等。
• include/：所有头文件。
• apps/：内置的应用层协议（如 MQTT、HTTP server）。

移植时第一原则是：不要改动src/目录里的源码逻辑，除非万不得已。你的移植层代码应该放在单独的目录中。

3.2 移植前的三个关键文件

LWIP 的移植核心其实只需要三个文件：

• lwipopts.h：这是 LWIP 的配置文件，定义了各种功能开关和参数。你可以把它理解为协议栈的“裁判”，哪些功能启用、哪些禁用，内存大小怎么分配，全在这里决定。
• arch/cc.h：这是编译器适配层，处理整型定义、字节序、断言、可变参数打印等。不同的编译器（GCC、MSVC、IAR）需要不同的配置。
• arch/sys_arch.h：这是操作系统抽象层，处理信号量、互斥锁、邮箱、线程。如果用NO_SYS=1（无 OS 模式），这个文件可以极其简单；如果用 OS 模式，就需要把原生 OS 的 API 映射到 lwip 上。

我在这次 Windows 移植过程中采用的是一个中间策略：NO_SYS=1，但不完全关掉线程支持。什么意思呢？就是让 lwip 跑在单线程模式，在主循环里不断调用sys_check_timeouts()处理超时，但 socket API 层的适配只保留最基础的功能。这样做的好处是编译简单、不依赖 pthread 库，坏处是你不能直接开多个进程/线程去并发调用 socket API。对于验证协议逻辑这个目的来说，完全够用。

3.3 最小可用的 lwipopts.h 配置

直接给你一份我在 Windows 上实测可用的最小配置，你可以把它放在项目的port/目录下，然后通过 CMake 添加 include 路径。这份配置的关键点已经用注释标出来了：

#ifndef LWIPOPTS_H #define LWIPOPTS_H // 不使用操作系统，直接跑在主循环里 #define NO_SYS 1 // 启用内存池和内存堆 #define MEM_LIBC_MALLOC 0 #define MEM_ALIGNMENT 4 #define MEM_SIZE (4 * 1024 * 1024) #define MEMP_NUM_PBUF 32 #define MEMP_NUM_TCP_SEG 64 // TCP/UDP 配置 #define LWIP_TCP 1 #define LWIP_UDP 1 #define TCP_MSS 1460 #define TCP_WND (4 * TCP_MSS) #define TCP_SND_BUF (8 * TCP_MSS) #define LWIP_NETCONN 1 #define LWIP_SOCKET 1 // 关闭不需要的功能，减小体积 #define LWIP_DHCP 0 #define LWIP_AUTOIP 0 #define LWIP_IGMP 0 #define LWIP_DNS 0 #define LWIP_NETIF_API 0 #define LWIP_ARP 1 // 关键宏：告诉 lwip 错误码由我们提供，避免和 Windows 的 errno 冲突 #define LWIP_PROVIDE_ERRNO 1 // 内存统计和调试开关，调试时开，发布时关 #define LWIP_STATS 1 #define LWIP_DEBUG 1 // 断言和自定义打印 #define LWIP_PLATFORM_ASSERT(x) do { printf("Assertion \"%s\" failed at line %d in %s\n", x, __LINE__, __FILE__); fflush(NULL); abort(); } while(0) #define LWIP_PLATFORM_DIAG(x) do { printf x; fflush(NULL); } while(0) // 时间戳精度 #define LWIP_RAND rand #endif

LWIP_PROVIDE_ERRNO这个宏是我重点标出来的坑。在 Windows 的 CRT 里其实是有 errno 的，但 lwip 的arch/cc.h里对 errno 的处理方式可能和 MSVC 的运行时库冲突。打开这个宏之后，lwip 会使用自己的 errno 定义，避免与系统头文件打架。这个坑在 Linux 上不存在，因为 glibc 对 errno 的兼容性很好，但在 Windows 上不设这个宏，编译后运行阶段大概率会出现 errno 值错乱的问题。

3.4 cc.h 里的编译器适配细节

arch/cc.h是另一个容易出问题的地方。我的做法是直接参考contrib/ports/unix里面的cc.h，然后改掉几个平台相关的地方。这里给出一个能用的版本：

#ifndef LWIP_ARCH_CC_H #define LWIP_ARCH_CC_H #include <stdio.h> #include <stdlib.h> #include <string.h> // 固定宽度整数类型 typedef unsigned char u8_t; typedef signed char s8_t; typedef unsigned short u16_t; typedef signed short s16_t; typedef unsigned int u32_t; typedef signed int s32_t; // 字节序 #define BYTE_ORDER LITTLE_ENDIAN // 编译器相关 #if defined(__GNUC__) #define PACK_STRUCT_FIELD(x) x __attribute__((packed)) #define PACK_STRUCT_STRUCT __attribute__((packed)) #define PACK_STRUCT_BEGIN #define PACK_STRUCT_END #endif // 可变参数打印 #define LWIP_PLATFORM_DIAG(x) do { printf x; fflush(NULL); } while(0) // 断言 #include <assert.h> #define LWIP_PLATFORM_ASSERT(x) assert(x) #endif

手动定义 u8_t、u16_t 这些类型，在 Windows 下没问题。如果你希望干净一点，也可以直接用<stdint.h>里的uint8_t等类型，然后适当 typedef。但如果把arch/cc.h里的字节序宏写错了，后续协议栈会非常难排查，因为乱的是链路层和 TCP 层的解析结果，表现通常是 IP 包校验错、TCP 连接建立不上，完全不像类型定义的问题。

4. 编写 CMakeLists.txt 构建 LWIP 静态库

4.1 工程目录结构

先把我项目里的目录结构摆出来，方便你对照：

project/ ├── CMakeLists.txt ├── port/ │ ├── lwipopts.h │ └── arch/ │ └── cc.h ├── src/ # lwip 源码，从 GitHub 拉取后原样放置 │ ├── core/ │ ├── api/ │ ├── netif/ │ └── include/ ├── app/ │ ├── tcp_echo_server.c │ └── main.c └── build/

build/目录用来放 CMake 的构建中间文件。有些人喜欢直接在源码根目录里建 build，也可以，但我建议还是独立出来，方便清理。

4.2 核心 CMake 配置：编译 lwip 库

写 CMakeLists.txt 的时候，目标很明确：把src/下的核心源文件编译成静态库，再链接到你的应用。直接给出一个能跑的版本：

cmake_minimum_required(VERSION 3.20) project(lwip_win_demo C) set(CMAKE_C_STANDARD 99) set(CMAKE_C_STANDARD_REQUIRED ON) # 指定编译器 set(CMAKE_C_COMPILER gcc) # 定义 lwip 库 add_library(lwip STATIC src/core/init.c src/core/mem.c src/core/memp.c src/core/netif.c src/core/def.c src/core/timeouts.c src/core/udp.c src/core/tcp.c src/core/tcp_in.c src/core/tcp_out.c src/core/ip.c src/core/ipv4/ip4.c src/core/ipv4/ip4_addr.c src/core/ipv4/etharp.c src/core/ipv6/ip6.c src/core/ipv6/ip6_addr.c src/api/api_lib.c src/api/api_msg.c src/api/err.c src/api/netbuf.c src/api/netdb.c src/api/netifapi.c src/api/sockets.c src/netif/ethernet.c ) target_include_directories(lwip PUBLIC src/include port ) target_compile_definitions(lwip PRIVATE LWIP_NOASSERT=0 LWIP_DEBUG=1 ) # 应用可执行文件 add_executable(lwip_demo app/main.c app/tcp_echo_server.c ) target_link_libraries(lwip_demo PRIVATE lwip)

这段配置有几个细节值得说明。

第一，源文件列表必须把依赖关系都覆盖到。如果你只用了 TCP，但是没加tcp_in.c和tcp_out.c，链接时就会出现tcp_input未定义的错误。这种错误其实很烦人，因为它要到链接阶段才暴露。一个比较稳的办法是把core/下所有.c文件都编译进来，虽然有点浪费体积，但能避免遗漏。

第二，target_include_directories里的port目录必须放在前面，确保lwipopts.h能覆盖 lwip 自带的默认配置。lwip 的include/lwip/opt.h里会对所有配置项给默认值，但开头有一段#ifdef LWIP_HDR_PORTS的逻辑，如果你的lwipopts.h存在，它会被优先包含。如果 include 顺序不对，可能用不上你的配置，那样默认配置通常也能编译通过，但内存参数和功能开关就不是你想要的了。

第三，LWIP_DEBUG宏我设成了 1，但如果你发现日志太刷屏，可以在你自己的lwipopts.h里通过LWIP_DBG_TYPES_ON去控制具体模块的日志输出，不用改 CMake。

4.3 实际构建操作：MinGW Makefiles 生成器

CMakeLists.txt 写好后，进入build目录执行：

cd build cmake -G "MinGW Makefiles" .. cmake --build .

这里有个大坑：如果你不指定-G，CMake 默认在 Windows 上会用 Visual Studio 生成器。如果系统里没装 Visual Studio，会报错；就算装了一个不匹配的版本，生成的也不是 Makefile，而是 MSBuild 工程。所以必须显式指定-G "MinGW Makefiles"。

另外，如果gcc和mingw32-make不在 PATH 里，CMake 可能能检测到gcc但找不到make，或者反过来。这时候你可以手动指定：

cmake -G "MinGW Makefiles" -DCMAKE_MAKE_PROGRAM=mingw32-make -DCMAKE_C_COMPILER=gcc ..

如果你愿意用 Ninja，也可以把生成器换成 "Ninja"，但需要额外安装 Ninja，我对 Windows 上的建议是老老实实用 MinGW Makefiles，少装一样是一样。

构建成功后，build/目录下会生成liblwip.a（静态库）和lwip_demo.exe。如果一切顺利，你已经完成了 80% 的移植工作。

5. 编译链接常见错误与排查

5.1 undefined reference 类错误

先讲最常见的错误。构建到最后一步链接时报：undefined reference to 'tcp_bind'或者undefined reference to 'lwip_init'。

这类问题十有八九是 CMakeLists.txt 里的源文件列表少了东西。排查思路有两个：一是看报错的符号属于 lwip 的哪个文件，去src/里用 grep 搜，比如：

grep -r "tcp_bind" src/core/ src/api/

搜到之后，确认对应.c文件已经加进 CMakeLists.txt。二是干脆把src/core/下所有.c文件都编译进库，省得一个个对齐。体积大点没关系，反正只是测试用。

还有一种情况：你配置了LWIP_NETCONN=1和LWIP_SOCKET=1，但忘了把src/api/下的api_lib.c、api_msg.c、sockets.c加进源文件列表。这同样会报 undefined reference，因为 netconn 和 socket API 的实现都在src/api/里。

5.2 头文件包含顺序与宏定义冲突

另一个高频问题：编译时报'ssize_t' does not name a type或者time相关的错误。这通常是因为 lwip 的头文件和 Windows 系统头文件之间的类型定义冲突了。

解决办法是在cc.h或lwipopts.h里明确引入<stddef.h>和<sys/types.h>。有些版本还需要：

#include <stdint.h> #include <stddef.h> #include <sys/types.h>

这些头文件提供了 ssize_t、size_t 等基础类型。在 Windows 的 MinGW-W64 环境下，顺序很重要。建议在cc.h里先#include <stdio.h>和<stdlib.h>，然后#include <stddef.h>，最后再包含 lwip 的其他头文件，能有效减少类型缺失问题。

5.3 字节序和宏定义陷阱

还有一类错误在 Windows 上特别容易踩，就是字节序。arch/cc.h里我写的是#define BYTE_ORDER LITTLE_ENDIAN，但如果你把BYTE_ORDER和BIG_ENDIAN这类宏跟系统宏冲突了，可能出现一个编译错误：'LITTLE_ENDIAN' undeclared。

为什么会出现这种情况？因为 MinGW-W64 自带<sys/param.h>和<endian.h>，里面也可能定义了BYTE_ORDER、LITTLE_ENDIAN等宏。如果你include了这些系统头文件，可能造成宏重定义。我的建议是：在cc.h里不要 include 任何系统相关的 endian 头文件，就把这三个宏直接定义好。反正 lwip 内部只关心字节序对不对，不关心你是从哪拿到的宏。

还有 lwip 的内存分配宏。默认情况下memp会使用静态数组，这是没问题的。但如果你的MEM_SIZE定义过大，在 Windows 上可能触发栈溢出或编译错误。这不是 lwip 本身的问题，而是 Windows 的堆栈限制和默认线程栈大小有关。如果你要加大内存池，记得在链接时指定更大的栈空间，或者干脆用MEM_LIBC_MALLOC=1走系统堆分配。

5.4 常见问题速查表

把你可能遇见的错误和解决思路整理成一个速查表：

6. 运行验证与最小测试框架

6.1 写一个最简单的 TCP Echo Server

构建完成后，你需要一个能真正跑起来的最小程序。我建议先写一个 TCP Echo Server，用 lwip 的 socket API 来实现，因为它的逻辑足够简单，能验证协议栈初始化和 TCP 收发链路。

app/tcp_echo_server.c的核心代码如下：

#include "lwip/init.h" #include "lwip/tcpip.h" #include "lwip/sockets.h" #include <stdio.h> #include <string.h> static void tcp_echo_server_thread(void *arg) { int listenfd = -1; int connfd = -1; char buf[2048]; int len; listenfd = lwip_socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); if (listenfd < 0) { printf("create socket failed\n"); return; } struct sockaddr_in serv_addr; memset(&serv_addr, 0, sizeof(serv_addr)); serv_addr.sin_family = AF_INET; serv_addr.sin_port = htons(8080); serv_addr.sin_addr.s_addr = htonl(INADDR_ANY); if (lwip_bind(listenfd, (struct sockaddr *)&serv_addr, sizeof(serv_addr)) != 0) { printf("bind failed\n"); return; } if (lwip_listen(listenfd, 5) != 0) { printf("listen failed\n"); return; } printf("echo server listening on 8080\n"); while (1) { connfd = lwip_accept(listenfd, NULL, NULL); if (connfd < 0) { continue; } // 接收并回射 while ((len = lwip_recv(connfd, buf, sizeof(buf), 0)) > 0) { lwip_send(connfd, buf, len, 0); } lwip_close(connfd); } }

在main.c里调用lwip_init()后，再调用sys_thread_new去启动这个线程。由于我们配置了NO_SYS=1，这里需要用 ke 线程的方式…等等，如果你设置NO_SYS=1，sys_thread_new其实不可用。所以要么启动时手动开一个 Windows 原生线程，要么把NO_SYS改成0并使用一个极简的 sys_arch 线程适配。我在移植时选择了在main里直接CreateThread创建线程来运行 tcp_echo_server 函数，这样既保持了 NO_SYS=1，又能在不用 pthread 的情况下并发运行 socket API。

6.2 在 Windows 下运行测试

编译完成后，运行lwip_demo.exe，用 Windows 自带的telnet或者写一个 Python 客户端去连本机 8080 端口：

# Python 客户端测试 python -c "import socket; s=socket.socket(); s.connect(('127.0.0.1',8080)); s.send(b'hello lwip'); print(s.recv(1024)); s.close()"

如果看到回射的数据，说明协议的 TCP/IP 链路已经通了。从这一刻开始，你就可以在这个框架上跑自己的协议逻辑了。

这一步有个细节：如果你运行程序后，端口 8080 被占用或者无法 bind，可以换个端口，或者检查是否已经有其他程序占用了端口。在 Windows 下可以用netstat -ano | findstr 8080来排查。

6.3 为什么协议栈卡在某个地方不动了

调试 lwip 时最诡异的一个现象是：程序跑起来了，也没有崩溃，但连接就是不建立，收不到任何数据。新手最容易忽略的是sys_check_timeouts()函数。

在 NO_SYS 模式下，lwip 的 TCP 重传定时器、ARP 缓存定时器主要靠sys_check_timeouts()来驱动。如果你代码里用了阻塞式的lwip_recv，而没有在一个单独的线程里调用sys_check_timeouts()，那么 TCP 的重传、超时检测都不会运行，就会卡在那里看起来像死锁。

解决办法是在程序中再加一个 Windows 原生线程，专门循环调用sys_check_timeouts()：

DWORD WINAPI lwip_timeout_thread(LPVOID arg) { while (1) { sys_check_timeouts(); Sleep(10); // 10ms 间隔 } return 0; }

这个细节在 Linux 下没那么明显，因为 Linux 的select和poll天然会把超时时间调度进去，但在 Windows 原生环境里，如果你用 lwip 自带的 socket API 且没有让系统内核去处理超时，很容易踩到。

6.4 一个更稳妥的建议：直接使用 contrib 里的 unix 移植

如果你不想手动维护cc.h和线程适配，可以走一个更省事的路子：直接用contrib/ports/unix提供的移植层，然后在 Windows 上用 MinGW-W64 编译它。contrib/ports/unix的源码本身是跨平台的 POSIX 实现，MinGW-W64 对 pthread 的支持也比较完善，只要安装了mingw-w64-x86_64-pthread或者使用 winlibs 自带的 pthread 支持，就能跑通。

这个方案的好处是省心，sys_arch层写得非常完整，官方也维护得很好。类似loopif、tapif这些驱动都可以用。坏处是又引入了 pthread 依赖，并且行为多少会带点 POSIX 风格。如果只是做协议逻辑验证，我推荐直接用这个现成的移植；如果你要完全原生 Windows 化、不依赖任何 POSIX 库，那就按照前面自己撸一套精简sys_arch。

7. 最后分享几个实用经验

这套流程跑通之后，我在几个项目里都沿用同样的方案，节省了大量重复搭建环境的时间。最后分享几个个人感触比较深的点。

第一个经验：把 lwipopts.h 里的所有内存池参数调得稍微大一点，特别是 MEMP_NUM_PBUF、MEMP_NUM_TCP_SEG、MEMP_NUM_ARP_QUEUE。这些参数默认值很保守，在嵌入式上够用，但在 Windows 上跑测试时，如果并发稍微高点，很容易出现 PBUF 分配失败、ARP 排队满的情况，然后表现为链路层丢包。排查起来非常痛苦，不如一开始就调大。

第二个经验：如果在 Windows 上跑 lwip 调试版本，建议把 LWIP_DEBUG 和 LWIP_STATS 同时打开。lwip 的调试输出是全写到标准输出上的，配合-Wall -Wextra编译，几乎能把所有可疑的地方都暴露出来。发布时再关掉这两个宏，性能影响可以忽略不计。

第三个经验：一定要做版本记录。lwip 版本升级有时候会调整 API 名称，比如tcp_connect的回调参数在 2.1.x 和 2.2.x 之间就有变化。如果项目是持续演进状态，建议把 lwip 的版本号写进README，或者用 Git submodule 锁住版本。不然复现问题的时候，你会发现别人给你传的代码根本编译不过，最后发现是 lwip 源码版本不一致，那种挫败感比今天遇到的问题还难受。

我在移植过程中最大的体会是：lwip 本身其实不难，难点全在工具链和平台差异上。只要把 CMake 和 MinGW-W64 这层先理顺，后面的流程和嵌入式几乎一模一样。希望这篇踩坑记录能帮你省几天的排查时间。