1. 为什么要在 STM32 上跑一个 HTTP 服务器
很多人第一次听到"在单片机上跑 HTTP 服务器"会觉得有点小题大做——一个几十块钱的 STM32F103，Flash 才 64KB、RAM 才 20KB，怎么可能像电脑一样对外提供网页服务？但实际做过工业网关、设备配置页、数据采集终端的人都知道，这个需求非常真实：设备部署到现场之后，你不可能每次都抱着笔记本插串口去改参数，最省事的办法就是让设备自己开一个网页，用手机或电脑浏览器连上去，改 IP、改采集周期、看实时数据，改完点保存，完事。
STM32 上实现这件事的标准路径就是LWIP + HTTPD。LWIP（Lightweight IP）是专门为嵌入式场景裁剪过的 TCP/IP 协议栈，完整实现可以压到 40KB 左右的 Flash 和十几 KB 的 RAM，配合 STM32 内置的以太网外设（比如 F107、F407、F429、H723 这些带 ETH MAC 的型号），再加上一颗 PHY 芯片（常见的 LAN8720A、DP83848），硬件链路就齐了。软件层面，CubeMX 已经把 LWIP 的移植工作做成了勾选项，HTTPD 组件也内置在中间件里，理论上点几下就能生成一个能跑的工程。
但"理论上"和"实际上"之间隔着一堆编译错误。我自己第一次搭的时候，Keil 报了十几个错，从sys_arch.h找不到，到lwipopts.h重复定义，再到ethernetif.c里的PHY读写超时，前后折腾了大半天。后来帮别人看工程，发现大家踩的坑高度重合——基本都是那几个：PHY 地址不对、时钟配置漏了、LWIP_HTTPD相关的宏没开、fsdata.c没生成或者路径不对。
这篇内容就是把这套流程拆成 5 个能落地的步骤，每一步说清楚"为什么这么做"和"这里最容易出什么问题"。适合两类人看：一类是刚接触 STM32 网络功能、想快速跑通一个 Demo 的；另一类是老手但每次换芯片型号都要重新踩一遍坑、想找个清单对照的。代码基于 STM32F407 + LAN8720A + Keil MDK 环境，CubeMX 版本用 6.x，LWIP 版本 2.1.2，其他型号思路一致，差异点我会单独标出来。
2. 动手之前先把硬件链路和软件版本理清楚
2.1 硬件最小系统需要哪些东西
跑 LWIP 不是光有 STM32 就行，以太网这部分是"MCU + PHY + 网络变压器 + RJ45"四件套。以 F407 为例，MCU 通过RMII 接口（比 MII 少一半引脚）连到 PHY，RMII 需要的外部时钟是 50MHz，这个时钟可以由 MCU 的 MCO 引脚输出给 PHY，也可以由外部晶振单独供给 PHY。我建议用 MCU 的 MCO 输出，省一颗晶振，但要注意 MCO 的分频配置必须和 PHY 期望的时钟一致，LAN8720A 要求 50MHz，F407 主频 168MHz 时 MCO 分频要设成 5 分频（168/5 不是整数，实际要用 PLL 的 25MHz 输出路径），这个细节后面配置时钟树的时候会具体说。
PHY 地址是个高频坑点。LAN8720A 的 PHY 地址由PHYAD0引脚在上电时决定，接下拉就是地址 0，接上拉就是地址 1。很多开发板原理图上没标清楚，代码里默认写 0，结果HAL_ETH_ReadPHYRegister一直返回超时。判断方法很简单：在初始化之后读一下 PHY 的 ID 寄存器（地址 0x02 和 0x03），LAN8720A 的 ID 应该是0x0007C0F1，读出来是0xFFFF或者0x0000就说明地址错了或者硬件没通。
网络变压器和 RJ45 一般用集成在一起的一体化接口，比如 HR911105A，这个没什么好说的，注意差分线走线尽量等长、远离高频干扰源就行。
2.2 CubeMX 和固件包的版本选择
CubeMX 我用的 6.10，固件包用 STM32Cube FW_F4 V1.28.0。这里有个经验：不要盲目追最新版。新版本固件包有时候会改 LWIP 的默认配置，比如某个版本把LWIP_NETIF_HOSTNAME默认关了，导致 HTTPD 里用主机名的地方编译不过。如果你跟着网上的老教程做，建议固件包版本和教程对齐，能省掉很多"为什么我的宏名字不一样"的困惑。
Keil MDK 用 5.38 以上，记得装好对应芯片的 Device Family Pack。另外 LWIP 的 HTTPD 组件依赖fsdata.c这个文件系统数据文件，它是用 ST 提供的makefsdata工具把网页文件转成 C 数组生成的，这个工具在固件包路径Middlewares/Third_Party/LwIP/system/下面，Windows 下是个 exe，Linux 下需要自己编译。很多人卡在"网页改了但设备上还是旧的"，就是因为忘了重新跑 makefsdata。
2.3 一个容易被忽略的前置检查
在打开 CubeMX 之前，先确认你的芯片型号确实带 ETH 外设。F103 系列（除了 F107）是没有以太网 MAC 的，如果你手上是 F103C8T6 这种最小系统板，那这条路走不通，得换 F107 或者外挂 W5500 这类 SPI 转以太网的芯片。这个检查花不了两分钟，但能避免你配了半天发现 CubeMX 里根本没有 ETH 选项。
3. CubeMX 里的五个关键配置区域
3.1 时钟树：RMII 的 50MHz 从哪来
打开 CubeMX 新建工程，选好芯片型号后第一件事是配时钟。以 F407 为例，外部晶振 8MHz，PLL 配置成主频 168MHz。然后在 Clock Configuration 页面找到MCO1或MCO2的输出配置，把它设成 50MHz 输出给 PHY。
具体操作：MCO2 的时钟源选 PLLI2SCLK，PLLI2S 的 N 值设成 50 的倍数关系，让输出正好是 50MHz。如果嫌麻烦，也可以让 PHY 用独立晶振，这样 MCO 就不用管了，但硬件上要多一颗 50MHz 的有源晶振，成本上不划算。
注意：MCO 输出的引脚是固定的（F407 上 MCO2 是 PC9），配置完之后要确认这个引脚没有被其他外设占用，否则 CubeMX 会报引脚冲突。
3.2 ETH 外设：RMII 模式和 PHY 地址
在 Connectivity 里找到 ETH，Mode 选RMII，下面的参数里 Advanced Parameters 中把 PHY Address 设成你硬件上实际的地址（默认 0）。Auto Negotiation 勾上，Speed 和 Duplex 设成 Auto。RX 和 TX 的 DMA 描述符数量保持默认就行，一般 RX 4 个、TX 4 个够用，如果后面发现丢包严重可以适当加大。
引脚方面，CubeMX 会自动分配 RMII 的 9 根线：REF_CLK、MDIO、MDC、CRS_DV、RXD0、RXD1、TX_EN、TXD0、TXD1。检查一下这些引脚和你原理图是否一致，特别是 REF_CLK，它既可以是 PHY 给 MCU 的，也可以是 MCU 给 PHY 的，方向搞反了链路起不来。
3.3 LWIP 中间件：HTTPD 相关的宏怎么开
在 Middleware 里勾选 LWIP，然后进入它的配置页面。这里分几个标签页，重点是General Settings和Key Options。
General Settings 里，LWIP_DHCP建议先关掉，用静态 IP 调试，跑通之后再开 DHCP。LWIP_ICMP和LWIP_UDP保持开启，ping 工具和后面可能的 UDP 调试都用得上。
Key Options 里要手动打开这几个宏：
LWIP_HTTPD设为 1，这是总开关LWIP_HTTPD_SUPPORT_POST设为 1，如果你要做表单提交（比如改参数）LWIP_HTTPD_DYNAMIC_HEADERS设为 1，支持动态生成响应头LWIP_HTTPD_SSI设为 1，支持 SSI（服务器端包含），做实时数据刷新要用LWIP_HTTPD_CGI设为 1，支持 CGI，处理表单和按钮操作
这几个宏不开，后面httpd.c编译的时候会有一堆函数找不到定义。我见过有人只开了LWIP_HTTPD，结果httpd_post_begin报未定义，就是因为 POST 支持没开。
3.4 生成代码前的最后检查
在 Project Manager 页面，Toolchain 选 MDK-ARM，注意不要勾选 "Generate peripheral initialization as a pair of .c/.h files"，这个选项会让 ETH 的初始化代码分散到单独文件里，和 LWIP 的ethernetif.c配合时容易出问题。保持默认的集中生成方式就好。
另外，Code Generator 里勾上 "Copy only necessary library files"，这样 LWIP 的源码会复制到工程目录下，方便你直接改lwipopts.h里的参数，不用去固件包目录里翻。
3.5 生成之后先别急着编译
点 Generate Code 之后，CubeMX 会生成完整的工程。这时候先别点编译，打开工程目录看一眼Middlewares/Third_Party/LwIP/src/apps/http/下面有没有httpd.c，以及fsdata.c在不在。如果fsdata.c缺失，说明 CubeMX 没有自动生成，需要你手动跑 makefsdata 工具，把网页文件转出来放进去。这个文件不在的话，编译会报FS_FILE相关的符号找不到。
4. 编译阶段最常见的六类错误及处理
4.1sys_arch.h找不到或者sys_mbox_t未定义
这个错误的根因是 LWIP 的sys_arch层没有正确包含。CubeMX 生成的工程里，sys_arch.c和sys_arch.h应该在Middlewares/Third_Party/LwIP/system/OS/下面。如果 Keil 的 Include Paths 里没有这个目录，编译器就找不到。
处理办法：在 Keil 的 Options for Target -> C/C++ -> Include Paths 里，确认包含以下路径（以 F407 工程为例）：
Middlewares/Third_Party/LwIP/src/include Middlewares/Third_Party/LwIP/system Middlewares/Third_Party/LwIP/system/OS Middlewares/Third_Party/LwIP/src/include/lwip Middlewares/Third_Party/LwIP/src/include/lwip/apps如果路径都在但还是报错，检查lwipopts.h里NO_SYS是不是设成了 0。NO_SYS=0表示使用操作系统模式，需要sys_arch支持；如果你没跑 RTOS，应该设成NO_SYS=1，用裸机模式，这样就不需要sys_arch了。CubeMX 默认会根据你是否启用 FreeRTOS 来设这个值，但有时候手动改过 FreeRTOS 配置后会不同步。
4.2lwipopts.h重复定义或者宏冲突
这个错误通常长这样：warning: "LWIP_DHCP" redefined。原因是 CubeMX 生成的lwipopts.h和你手动添加的另一个配置文件同时被包含了。检查一下工程里是不是有两个lwipopts.h，一个在Core/Inc/下，一个在Middlewares/下。CubeMX 生成的是前者，后者可能是你从别处拷来的。
解决办法：只保留Core/Inc/lwipopts.h，把另一个删掉或者从 Include Paths 里移除。如果确实需要自定义配置，直接改Core/Inc/lwipopts.h里的内容，不要另起炉灶。
4.3ethernetif.c里的 PHY 读写超时
编译能过，但下载运行后卡在ethernetif_init或者low_level_init里，串口打印PHY read timeout。这个问题的排查链路是这样的：
第一步，确认 PHY 地址。在ethernetif.c里找到LAN8720_GetLinkState或者类似的函数，看它用的地址是不是 0。如果不是，改成你硬件上的实际地址。
第二步，确认 MDC 时钟。MDC 是 PHY 管理接口的时钟，由 MCU 的 ETH_MDC 引脚输出，频率不能超过 2.5MHz。CubeMX 里 ETH 的 Advanced Parameters 有个 MDC Clock Range，F407 主频 168MHz 时选 150-168MHz 这一档，分频后大约是 2.1MHz，符合要求。如果选错了档位，MDC 太快或太慢都会导致读写失败。
第三步，用示波器或者逻辑分析仪看 MDIO 线上有没有波形。如果没有，说明 MCU 的 ETH 外设根本没启动，回去检查 ETH 的时钟使能和 GPIO 复用配置。
4.4fsdata.c相关的FS_FILE未定义
这个错误说明 HTTPD 的文件系统数据没有正确链接。fsdata.c里定义了一个static const unsigned char data_index_html[]这样的数组，以及一个struct fsdata_file file_index_html[]的结构体。如果fsdata.c没有被加入编译，或者LWIP_HTTPD_USE_CUSTOM_FSDATA宏设成了 1 但你没有提供自定义的 fsdata，就会报这个错。
处理办法：确认fsdata.c在 Keil 工程的 Source Group 里，并且LWIP_HTTPD_USE_CUSTOM_FSDATA设为 0（用默认的 fsdata）。如果你要自己生成网页数据，把这个宏设成 1，然后把你生成的fsdata.c放到工程里替换掉默认的。
4.5 中断向量表里ETH_IRQHandler重复定义
CubeMX 生成的stm32f4xx_it.c里已经定义了ETH_IRQHandler，如果你在别的地方（比如自己写的ethernetif.c里）又定义了一遍，链接时会报重复符号。解决办法是只保留一处，通常保留stm32f4xx_it.c里的，然后在里面调用 LWIP 的中断处理函数ethernetif_input。
4.6 堆栈溢出导致的 HardFault
LWIP 运行需要一定的堆内存，lwipopts.h里的MEM_SIZE默认可能是 1600 字节，对于 HTTPD 来说偏小。建议改成 4096 或者 8192。同时 Keil 的启动文件里Heap_Size也要相应加大，至少 0x1000。如果跑起来之后随机 HardFault，优先怀疑堆不够。
5. 让网页真正跑起来的收尾工作
5.1 静态 IP 配置和 ping 测试
在lwipopts.h里确认LWIP_DHCP是 0，然后在main.c的MX_LWIP_Init()之后，用netif_set_addr设置静态 IP。或者更简单，直接在 CubeMX 的 LWIP General Settings 里填 IP 地址、子网掩码、网关。生成之后这些值会写到lwipopts.h或者ethernetif.c里。
下载运行后，把电脑的网口和板子用网线直连（或者接到同一个交换机），电脑 IP 设成和板子同网段，比如板子是 192.168.1.100，电脑设 192.168.1.10。打开命令行 ping 一下：
ping 192.168.1.100能通说明链路层和网络层都正常。如果不通，先看板子上的 Link 灯和 Speed 灯亮不亮，不亮就是 PHY 没协商成功，回去检查硬件和 PHY 配置。
5.2 浏览器访问和 SSI 数据刷新
ping 通之后，浏览器输入http://192.168.1.100，应该能看到默认的网页。CubeMX 生成的默认网页很简单，就是一个 "STM32" 的标题。如果你要显示实时数据，比如 ADC 采样值，需要在网页里用 SSI 标签，比如<!--#adc_value-->，然后在httpd_cgi_ssi.c里实现对应的处理函数，把变量值填进去。
SSI 的处理函数签名是这样的：
const char *ssi_tags[] = {"adc_value", NULL}; u16_t ssi_handler(int iIndex, char *pcInsert, int iInsertLen) { if (iIndex == 0) { snprintf(pcInsert, iInsertLen, "%d", get_adc_value()); } return strlen(pcInsert); }然后在httpd_init之后调用http_set_ssi_handler(ssi_handler, ssi_tags, 1)注册进去。这样每次网页刷新，adc_value的位置就会显示当前的 ADC 值。
5.3 POST 表单处理参数保存
如果你要做参数配置页，比如改采集周期，网页里放一个<form method="post" action="/save">，里面一个输入框name="period"。在httpd_cgi_ssi.c里实现httpd_post_begin和httpd_post_data_recved两个回调，把收到的数据解析出来存到 Flash 或者备份寄存器里。
这里有个坑：httpd_post_data_recved可能会被多次调用，因为 POST 数据是分片到达的。你需要自己维护一个缓冲区，把所有分片拼起来再解析。我一般用一个 256 字节的静态数组，加一个索引变量，在httpd_post_begin里清零，在httpd_post_data_recved里追加，在httpd_post_finished里做最终解析。
5.4 实测中的性能表现和优化方向
F407 主频 168MHz，跑 LWIP HTTPD，用浏览器访问静态页面，响应时间在 10ms 以内，感觉不到延迟。如果页面里有很多图片，首次加载会慢一些，因为fsdata.c是把所有文件都编译进 Flash 的，读取速度受 Flash 访问速度限制。优化办法是把不常变的图片放到外部 SPI Flash 里，用 LWIP 的fs_open_custom回调按需读取。
并发方面，LWIP 默认支持 5 个 TCP 连接（MEMP_NUM_TCP_PCB），对于设备配置页来说够用了。如果要做多客户端同时访问，把这个值加大到 10，同时把MEMP_NUM_TCP_PCB_LISTEN也相应调整。
6. 几个我踩过之后才明白的细节
第一个是关于LWIP_NETIF_HOSTNAME。这个宏默认是关的，但 HTTPD 的某些示例代码里会用netif->hostname，不开就编译不过。如果你遇到struct netif has no member named hostname，把这个宏打开就行。
第二个是TCPIP_THREAD_STACKSIZE。如果你跑 FreeRTOS + LWIP，这个值默认可能是 1024，对于 HTTPD 来说偏小，处理 POST 数据的时候容易栈溢出。改成 2048 或者 4096，具体看你的页面复杂度。
第三个是网页文件的路径。makefsdata工具默认会把当前目录下的所有文件打包，包括子目录。但生成的fsdata.c里文件路径是相对的，比如index.html对应/index.html。如果你在网页里用了/images/logo.png这样的绝对路径，确保makefsdata运行时images目录就在当前目录下，否则会 404。
第四个是关于缓存。浏览器会缓存网页，你改了设备上的网页之后，浏览器可能还是显示旧的。调试的时候按 Ctrl+F5 强制刷新，或者用无痕模式打开。
这套流程走下来，从新建工程到浏览器能看到页面，熟练的话半小时以内能搞定。第一次做的话，把编译错误那一节对照着排查，基本两三个小时也能跑通。关键是要理解每一步在做什么，而不是照着步骤点一遍——因为换个芯片型号或者换个 PHY，总有一两个参数要改，理解了原理才能自己定位问题。
