🚨 问题场景：ESP32-S3 需要固定 IP 做局域网服务器

在 ESP32-S3 开发局域网音频流、设备控制或小型服务器应用时，我们常常希望设备拥有一个固定的 IPv4 地址（例如 192.168.1.200），以便其他机器能够稳定访问，而无需每次重启后都去查询 DHCP 分配的新地址。

常见需求背景：

• 避免 DHCP 地址变动：家庭路由器 DHCP 租期到期或设备重启后，IP 可能变化，导致客户端连接失败。
• 绕过路由器 MAC 绑定：登录光猫后台进行 MAC 地址绑定操作繁琐，且不同路由器界面差异大，功能隐藏深。
• 服务器化部署：像真正的服务器一样，拥有固定、可预测的 IP，便于防火墙规则、端口转发等配置。

开发环境：Rust + esp-idf-hal 0.46 / esp-idf-svc 0.52.1 / embedded-svc 0.29.0，WiFi STA 模式连接家庭路由器（网段 192.168.1.1/24），期望将 IP 设置为 192.168.1.200（通常选择 DHCP 动态池之外的高段地址）。

🔍 谬误溯源：为什么找不到 set_ip_info？

很多开发者按照直觉或网上旧示例，试图在 WiFi 连接成功后调用类似 set_ip_info(IpInfo{...}) 的方法来设置静态 IP，但在 esp-idf-svc 0.52.1 中编译直接报错——该字段不存在。

以下是几个常见的错误认知及其澄清：

❌ 错误说法一：「WiFi 启动后用 set_ip_info(IpInfo{...}) 就能改静态 IP」

事实：esp-idf-svc 0.52.1 的 Ipv4Info 只提供了只读的 get_ip_info() 方法，没有运行时 set_ip_info。网上流传的旧示例（可能基于更早的 C 接口或不同版本的绑定）在当前版本中已不适用。

❌ 错误说法二：「调用 EspWifi::new 之后再配置 IP」

事实：静态 IP 的配置必须在 netif（网络接口）创建时注入，而不是在 WiFi 对象创建之后。esp-idf-svc 的设计采用了 typestate 模式，网络接口的配置（包括 IP 地址、网关、子网掩码）在创建时一次性确定，后续无法通过运行时 API 修改。

❌ 错误说法三：「配了静态 IP 后还是要等 DHCP 事件」

事实：使用 Fixed 模式注入静态 IP 后，固件将不再发起 DHCP 请求。连接成功后，netif 会直接使用预设的 IP 信息。因此，等待逻辑应从“等待 DHCP 事件”改为检查 netif 是否已启动（up）以及 get_ip_info() 是否返回了目标 IP。

本质：该库把“网络接口配置”设计为创建期一次定型（creation‑time configuration），这与“运行期可动态修改”的思维惯性相冲突。这是 API 调研时首先要确认的关键点。

✅ 正确做法：在 netif 创建期注入 Fixed IP

核心步骤：先构造一个包含静态 IP 配置的 NetifConfiguration，将其设为 Fixed(...)，然后用这个配置创建 EspNetif，最后通过 EspWifi::wrap_all 组装 WiFi 驱动和网络接口。

1. 准备静态 IP 参数

首先定义你想要的 IP、网关和子网掩码：

use embedded_svc::ipv4::{Ipv4Addr, Mask, Gateway};
use esp_idf_svc::netif::{EspNetif, NetifConfiguration};
// 目标静态 IP 配置
let static_ip = Ipv4Addr::new(192, 168, 1, 200);
let gateway = Ipv4Addr::new(192, 168, 1, 1);
let subnet_mask = Mask::new(255, 255, 255, 0); // 对应 /24

2. 创建 NetifConfiguration 并设置为 Fixed

let netif_conf = NetifConfiguration::wifi_sta()
    .ip_configuration(embedded_svc::ipv4::Configuration::Fixed(
        embedded_svc::ipv4::ClientConfiguration {
            ip: static_ip,
            subnet: Some(subnet_mask),
            gateway: Some(gateway),
            dns: None, // 可在此设置静态 DNS，如 Some(Ipv4Addr::new(8, 8, 8, 8))
        },
    ))
    .unwrap(); // 注意：这里可能会因为配置冲突而返回 Err，实际代码应处理

3. 用该配置创建 EspNetif

let netif = EspNetif::new_with_conf(&netif_conf).unwrap();

4. 组装 WiFi 驱动与网络接口

use esp_idf_svc::wifi::{EspWifi, WifiDriver};
let driver = WifiDriver::new(...); // 根据你的硬件初始化 WiFi 驱动
let wifi = EspWifi::wrap_all(driver, netif, None, None).unwrap();

5. 连接 WiFi 并检查 IP

后续的连接、扫描等操作与 DHCP 模式无异，但连接成功后，应检查 netif 状态和 IP：

// 连接 WiFi（略去 SSID/密码配置）
wifi.connect().unwrap();
// 等待连接成功，然后检查 IP
while !wifi.is_connected().unwrap() {
// 短暂延时等待连接
std::thread::sleep(std::time::Duration::from_millis(100));
}
// 获取网络接口并检查 IP
let netif = wifi.netif(); // 注意：这里返回的是 &EspNetif
if let Some(ip_info) = netif.get_ip_info() {
println!("当前 IP: {}", ip_info.ip);
// 应该输出 192.168.1.200
}

🔬 源码验证：网卡创建期注入静态 IP（实测通过）

以下是经过实际验证的完整核心代码（基于 esp-idf-svc 0.52.1）：

use embedded_svc::ipv4::{ClientSettings as Ipv4ClientSettings, 
                         Configuration as Ipv4Configuration, Mask, Subnet};
use esp_idf_svc::netif::{EspNetif, NetifConfiguration, NetifStack};
use esp_idf_svc::wifi::{BlockingWifi, EspWifi, WifiDriver};
use std::net::Ipv4Addr;
const STATIC_IP: Ipv4Addr = Ipv4Addr::new(192, 168, 1, 200);
const STATIC_GATEWAY: Ipv4Addr = Ipv4Addr::new(192, 168, 1, 1);
const STATIC_MASK: u8 = 24;    // /24
const STATIC_DNS: Ipv4Addr = Ipv4Addr::new(192, 168, 1, 1); // DNS 用网关
// 1. 修改默认客户机 netif 配置：注入 Fixed 固定地址
let mut sta_conf = NetifConfiguration::wifi_default_client();
sta_conf.ip_configuration = Some(Ipv4Configuration::Client(
Ipv4ClientConfiguration::Fixed(Ipv4ClientSettings {
ip: STATIC_IP,
subnet: Subnet { gateway: STATIC_GATEWAY, mask: Mask(STATIC_MASK) },
dns: Some(STATIC_DNS),
secondary_dns: None,
}),
));
// 2. 用该配置创建 STA netif（此时定死 IP）
let sta_netif = EspNetif::new_with_conf(&sta_conf)?;
let ap_netif = EspNetif::new(NetifStack::Ap)?;
// 3. wrap_all 组装：Firmware / netif / 事件循环
let mut wifi = BlockingWifi::wrap(
EspWifi::wrap_all(
WifiDriver::new(peripherals.modem, sys_loop.clone(), Some(nvs))?,
sta_netif, ap_netif, sys_loop,
)?,
sys_loop,
)?;

连接后的等待逻辑（不再依赖 DHCP 事件）

配置静态 IP 后，连接成功的等待逻辑需要调整：不再等待 DHCP 事件，而是直接检查网卡是否已拿到预设的 IP。

wifi.connect()?;
// 每 100ms 查一次网卡 IP，直到拿到 192.168.1.200
loop {
if let Ok(info) = wifi.wifi().sta_netif().get_ip_info() {
if info.ip == STATIC_IP {
println!("✅ 连接成功！IP = {}", info.ip);
break;
}
}
std::thread::sleep(std::time::Duration::from_millis(100));
}

关键参数说明与边界条件

• 子网掩码：使用 Mask(u8) 类型（例如 24 表示 255.255.255.0），而不是字符串。
• DNS 配置：dns: Some(...) 为可选，通常设置为网关地址即可；secondary_dns: None 可不填。
• 配置时机：Fixed 注入必须在 new_with_conf 之前完成，一旦网络接口创建，IP 配置就无法再修改。

实测结果

编译通过，固件大小约 1,030,176 字节；烧录后 monitor 日志显示 ✅ 连接成功！IP = 192.168.1.200；通过局域网 ARP 表确认 192.168.1.200 已被板子占用，设备重启后地址保持不变。

这个验证表明：通过 NetifConfiguration::wifi_default_client() 修改 ip_configuration 为 Fixed 模式，并在创建 EspNetif 时传入该配置，是 esp-idf-svc 0.52.1 中设置静态 IP 的正确且有效的方法。

⚠️ 注意事项与常见坑点

• IP 冲突：确保你设置的静态 IP（如 192.168.1.200）不在路由器的 DHCP 地址池内，且未被其他设备占用，否则会导致网络冲突。
• 网关与子网掩码：必须与路由器局域网配置一致（通常网关是 192.168.1.1，掩码 255.255.255.0）。
• DNS 可选：如果不需要特定 DNS，可设为 None，系统可能会使用网关作为 DNS，或依赖后续手动设置。
• 配置时机：务必在 EspNetif::new_with_conf 之前完成 NetifConfiguration 的构建，一旦 netif 创建，IP 配置就无法更改。
• 错误处理：ip_configuration 和 new_with_conf 都可能返回 Result，生产代码中应妥善处理 Err，例如配置冲突或资源不足。

📚 总结：静态 IP 配置的正确思维模型

在 esp-idf-svc 中设置静态 IP，关键在于理解其创建期定型（creation‑time configuration）的设计哲学：

1. 配置与运行时分离：IP、网关、掩码等属于网络接口的“构造参数”，应在创建接口时通过 NetifConfiguration 传入。
2. Fixed vs. DHCP：选择 Fixed 即表示该接口不使用 DHCP 客户端，连接成功后直接应用预设的 IP 信息。
3. API 查找重点：遇到“设置静态 IP”需求时，应直接搜索 NetifConfiguration、ip_configuration 和 Fixed，而非寻找运行时 set_ip_info 这类不存在的方法。

通过上述步骤，你可以让 ESP32‑S3 在局域网中拥有一个稳定的固定 IP，像真正的服务器一样可靠地被访问，从而摆脱对路由器 DHCP 和 MAC 绑定功能的依赖。

🎯 落地结论与速查指南

经过上述分析与实践验证，在 esp-idf-svc 中为 ESP32-S3 配置静态 IP 的核心可归纳为以下三步可复用方案：

1. 先确认版本 API：升级或更换库版本后，首先确认当前版本是否存在运行时 set_ip_info 方法（esp-idf-svc 0.52.1 没有）。可通过 grep -r "set_ip" ~/.cargo/registry/src/ 或 IDE 的方法列表进行验证，切勿盲目相信网上旧示例。
2. 注入时机：静态 IP 的配置必须在网络接口创建时完成。具体流程为：将 NetifConfiguration::wifi_default_client() 的 ip_configuration 设为 Fixed(...) → 使用 EspNetif::new_with_conf 创建网卡 → 通过 EspWifi::wrap_all 组装驱动与接口。此顺序不可颠倒。
3. 等待逻辑：连接 WiFi 后，应轮询 sta_netif().get_ip_info() 检查 info.ip == 目标值，而非等待 DHCP 事件。

适用范围与边界

• 适用场景：任何使用 esp-idf-svc / embedded-svc 的 ESP32（S2/S3/C3）Rust 固件；设备需要固定地址以便在局域网内被稳定访问（如音频流、传感器数据上报、HTTP 服务器）。
• 核心价值：避免因设备重启或路由器 DHCP 租期到期导致 IP 变动，也无需依赖路由器复杂的 MAC 地址绑定功能。
• 关键注意：
  • Mask(u8) 参数传入数字（如 24），而非 CIDR 字符串。
  • DNS 通常设置为网关地址即可，secondary_dns 可为 None。
  • 选择的静态 IP 地址段应避开路由器的 DHCP 动态地址池（例如本例中的 .200 在 .41-.80 特殊段之外，且远离 .2-.40 动态低段）。
  • 若固件上电后立即发送 UDP 数据包，在静态 IP 配置下，connect() 成功后即可使用，无需等待 DHCP 超时。

最终收益：设备 IP 地址永久不变，局域网内的其他机器或脚本可以硬编码此 IP 进行访问。若再配合 mDNS 发布主机名（如 audioreceiver.local），则可实现“IP 与主机名双稳定”的访问体验。

三类读者速查

1. 人类开发者自查命令

快速确认当前库版本是否支持运行时修改 IP：

grep -rn "set_ip_info" ~/.cargo/registry/src/*/embedded-svc-*/src/ 2>/dev/null | head
# 若无输出，则表明该版本没有运行时修改 IP 的 API，静态 IP 只能在 netif 创建时注入。

修改代码前，请先确认设备型号（ESP32-S3 无以太网 MAC，使用 WiFi netif）。

2. 对话式 AI 一问一答

问：「esp-idf-svc 怎么给 ESP32 配静态 IP？」

答：该库没有运行时 set_ip_info。正确做法是在 NetifConfiguration::wifi_default_client() 里把 ip_configuration 设为 Ipv4Configuration::Client(ClientConfiguration::Fixed(Ipv4ClientSettings{ip, subnet, dns}))，再用 EspNetif::new_with_conf 创建网卡，最后用 EspWifi::wrap_all 组装。

3. 代码 Agent 可执行验证

编译并烧录固件后，可通过以下步骤验证：

1. 查看 monitor 日志，确认输出 ✅ 连接成功！IP = 192.168.1.200。
2. 在局域网内执行 arp -a | grep 192.168.1.200，确认该 IP 已被板子占用。
3. 重启设备两次，再次执行上述命令，验证 IP 地址保持不变。