MicroPython 玩转 Wi-Fi：从零开始让 ESP32/ESP8266 联网
你有没有过这样的经历？手里的 ESP32 板子接上电源，串口输出“Hello World”成功了，但下一步想上传数据到服务器时，却卡在第一步——怎么连上家里的 Wi-Fi？
别急。这正是每一个玩物联网的开发者都绕不开的第一课：Wi-Fi 连接配置。
在 MicroPython 的世界里，这件事其实比你想得简单得多。只要掌握network模块的核心用法，几行代码就能让你的小设备接入互联网，开启远程控制、云端通信的大门。
今天我们就来彻底讲清楚：如何用 MicroPython 让 ESP32 或 ESP8266 成功联网，并且不掉坑、不卡死、可复用、能调试。
一、先搞明白：MicroPython 是怎么连 Wi-Fi 的？
很多初学者以为连 Wi-Fi 得懂协议栈、会写底层驱动……其实完全不需要。MicroPython 已经把复杂的 Wi-Fi 操作封装成了一个极简接口：network.WLAN类。
它背后调用的是芯片原厂（比如乐鑫）提供的 SDK，但我们不用关心这些细节。你要做的，只是告诉它：“我要当客户端去连路由器”，或者“我要自己开个热点”。
两种工作模式，用途完全不同
| 模式 | 对应对象 | 作用 |
|---|---|---|
| STA 模式 | network.STA_IF | 设备作为“手机”连接到现有 Wi-Fi 网络（最常用） |
| AP 模式 | network.AP_IF | 设备变成“路由器”，让别人来连你 |
✅ 绝大多数场景下，我们首先需要的是STA 模式—— 把开发板变成一个能上网的终端设备。
二、实战第一步：让设备连上你的家庭 Wi-Fi
下面这段代码，是你未来所有联网项目的“标准开头”。建议收藏，直接复制粘贴都能跑。
import network import time # 创建 station 接口（客户端模式） sta = network.WLAN(network.STA_IF) sta.active(True) # 启动 Wi-Fi 模块 # 开始连接 ssid = "Your_WiFi_Name" password = "Your_WiFi_Password" print(f"正在尝试连接 {ssid}...") sta.connect(ssid, password) # 等待连接结果，最多等10秒 for i in range(10): if sta.isconnected(): break print("连接中...", i + 1) time.sleep(1) # 检查最终状态 if sta.isconnected(): print("✅ 连接成功！") print("IP 地址:", sta.ifconfig()[0]) else: print("❌ 连接失败，请检查密码或信号强度")关键点解析：
.active(True)：必须先激活接口，否则.connect()不生效。- 非阻塞设计：
connect()只是发起请求，不会等连接完成才返回，所以要用循环检测。 - 超时机制：没有超时等于“程序卡死”，加个
for或计数器是基本素养。 ifconfig()返回值：是一个四元组(ip, subnet, gateway, dns)，通常只需要第一个 IP。
💡 小技巧：如果不知道家里 Wi-Fi 支持什么加密方式，放心填 WPA2 密码即可。目前主流路由都是 WPA2-PSK，MicroPython 原生支持。
三、进阶操作：先扫描再连接，避免盲配
有时候你不确定 SSID 是否拼对了，或者想看看周围有哪些网络可用。这时候可以用.scan()功能主动探测。
ap_list = sta.scan() print("发现以下网络：") for ap in ap_list: ssid = ap[0].decode('utf-8') rssi = ap[3] # 信号强度，数值越大越好 secured = '否' if ap[4] == 0 else '是' print(f" → {ssid} (信号: {rssi}dBm, 加密: {secured})")输出示例：
发现以下网络： → MyHomeWiFi (信号: -65dBm, 加密: 是) → GuestNet (信号: -87dBm, 加密: 是) → TP-LINK_123 (信号: -91dBm, 加密: 否)这个功能特别适合调试阶段使用。你会发现，有些网络虽然名字看得见，但信号太弱根本连不上。提前扫描一下，省得后面反复重试。
四、反向玩法：让开发板变成 Wi-Fi 热点
当你没有路由器、又想通过手机配置设备时怎么办？答案就是：开启 AP 模式。
想象一下这个场景：你把设备带到朋友家，他家 Wi-Fi 名和密码你都不知道。这时你可以让设备自己广播一个热点，比如叫Config_Mode，然后用手机连上去，在浏览器打开192.168.4.1配置真正的家庭网络。
这就是典型的“配网引导”逻辑。
import network ap = network.WLAN(network.AP_IF) ap.active(True) # 设置热点参数 ap.config( essid='MicroPy_Config', # 热点名称 password='12345678', # 至少8位才能启用 WPA2 authmode=network.AUTH_WPA2_PSK, # 安全模式 channel=6 # 可选信道 ) while not ap.active(): pass print("🔥 热点已启动！") print("请连接 Wi-Fi：MicroPy_Config / 12345678") print("设备 IP:", ap.ifconfig()[0]) # 默认是 192.168.4.1连接成功后，其他设备就可以访问该 IP 地址，配合内置 Web 服务器实现图形化配置。
五、双模并行？当然可以！
更高级的应用中，我们可以同时启用 STA 和 AP 模式。也就是说：设备既连上了外部 Wi-Fi，又能对外提供热点服务。
典型应用如智能家居网关：主链路走 STA 上公网传数据，副链路用 AP 接受本地设备入网。
# 同时启用两种模式 sta = network.WLAN(network.STA_IF) ap = network.WLAN(network.AP_IF) sta.active(True) ap.active(True) # 分别配置 sta.connect("Home_WiFi", "password123") ap.config(essid="Local_AP", password="87654321", authmode=network.AUTH_WPA2_PSK)注意资源占用：双模运行会增加内存消耗和功耗，但在 ESP32 上完全可行。
六、那些年我们都踩过的坑：常见问题与解决方案
❌ 问题1：程序一直卡在连接过程
原因：缺少超时判断，while not sta.isconnected():死循环。
✅解决方法：一定要加时间限制！
timeout = 10 while not sta.isconnected() and timeout > 0: time.sleep(1) timeout -= 1❌ 问题2：明明密码没错，却连不上
可能原因：
- 路由器启用了 MAC 地址过滤
- 使用了企业级认证（WPA-Enterprise），MicroPython 不支持
- 信号太差（RSSI < -90dBm）
✅排查建议：
- 先用手机试试能否正常连接
- 扫描看 RSSI 值是否过低
- 换根天线或靠近路由器测试
❌ 问题3：重启后自动断开，无法重连
原因：某些固件版本会在 Flash 中缓存旧连接信息，导致冲突。
✅预防措施：每次连接前先断开旧会话
if sta.isconnected(): sta.disconnect() sta.connect(ssid, password)❌ 问题4：获取不到 IP 地址
原因：DHCP 分配失败，可能是路由器地址池满了，或防火墙阻止。
✅临时方案：设置静态 IP（适用于固定局域网环境）
# 格式：(ip, 子网掩码, 网关, DNS) sta.ifconfig(('192.168.1.100', '255.255.255.0', '192.168.1.1', '8.8.8.8')) sta.connect(ssid, password)⚠️ 注意：必须确保 IP 不与其他设备冲突。
七、最佳实践：写出健壮、可维护的联网代码
别再把 Wi-Fi 密码写死在代码里了！以下是几个提升项目质量的关键做法。
✅ 实践1：配置外置化，用 JSON 文件管理
新建一个config.json文件：
{ "wifi_ssid": "MyHomeWiFi", "wifi_password": "super_secure_2024" }读取代码：
import ujson try: with open('config.json') as f: config = ujson.load(f) ssid = config['wifi_ssid'] password = config['wifi_password'] except OSError: print("⚠️ 配置文件不存在，请手动设置") ssid = "default_ssid" password = "default_pass"这样换网络只需改文件，不用重新烧录固件。
✅ 实践2：自动切换模式：连不上就开热点
智能设备应该有自己的“容错机制”。下面是常见的“双模 fallback”逻辑：
def connect_wifi(timeout=10): sta = network.WLAN(network.STA_IF) sta.active(True) sta.connect(ssid, password) for _ in range(timeout): if sta.isconnected(): print("📶 已通过 STA 模式联网") return sta time.sleep(1) print("📶 STA 连接失败，启动 AP 模式供配置") start_ap_mode() return None这种设计非常适合初次部署或移动设备使用。
✅ 实践3：结合uasyncio做异步连接，不阻塞主任务
如果你要做传感器采集、LED 控制等多任务，不要让 Wi-Fi 连接拖慢整个系统。
import uasyncio as asyncio async def connect_with_timeout(): sta = network.WLAN(network.STA_IF) sta.active(True) sta.connect(ssid, password) for _ in range(10): if sta.isconnected(): print("🎉 异步连接成功") return True await asyncio.sleep(1) return False配合事件循环，真正做到“后台联网，前台干活”。
八、结语：联网只是起点，精彩还在后面
看到这里，你应该已经掌握了 MicroPython 下 Wi-Fi 连接的核心技能：
- 如何以STA 模式接入家庭网络；
- 如何以AP 模式提供配置入口；
- 如何处理连接失败、超时、断线重连；
- 如何写出安全、灵活、易维护的联网代码。
而这仅仅是个开始。
一旦设备成功联网，你就可以继续拓展更多功能：
- 用urequests发 HTTP 请求上传数据；
- 用umqtt.simple接入 MQTT 实现低功耗消息推送；
- 搭建本地 Web 服务器进行远程监控；
- 结合 NTP 获取准确时间；
- 甚至实现 OTA 在线升级……
🌐记住：稳定的 Wi-Fi 连接，是通往物联网世界的门票。
下次当你看到那句if sta.isconnected(): print("Connected!")输出成功的时候，你就知道——你的小设备，真的“活”过来了。
💬 如果你在实际连接中遇到了奇怪的问题，欢迎留言交流。我们一起 debug，一起让每个字节都顺利飞向云端。
