ESP32-S3 的实验台：32 个可玩实验，固件逐行读给你听

学 ESP32-S3 的门槛常常不在代码，而在第一步——板子还没到、线不知道往哪插、一千多页的技术参考不知道从哪读。这个项目把整张实验台搬进了浏览器：32 个实验，每个都给出引脚、接线、烧录命令和一个能在网页上直接玩的模拟器；真实固件不用你猜，代码阅读器会几行一停地讲，还能跟着 setup() 一路走下去。

卡点通常不在代码

第一次摸 ESP32-S3 的人，卡住的地方高度相似。其一是等板子：想先看看某个外设值不值得做，得先下单、等快递、装工具链，等真能动手时热情已经凉了一半。其二是接线：教程里一句「把 SDA 接到 GPIO8」，落到实物上是有几十个引脚的排针，接错了还得排查是线的问题还是代码的问题。其三是文档：乐鑫的手册写得详实，但一千多页的技术参考摆在面前，新手根本不知道哪一节和自己此刻要做的事有关。

先让你在浏览器里把现象看到、把命令敲熟，再谈动手。首页那句话就是它的结构——接线、烧录、看现象、读代码，每一步都有一个对应的界面。

现成的学习资源其实不少，但大部分是单向的：视频看完不知道自己哪一步做错了，博客里的接线照片换了板子版本就对不上，官方例程倒是能跑，却不解释为什么这么写，改一个参数就不知道后果。这个项目补的是「可验证」这一环——每一步都给你一个能立刻看到反馈的界面，做对了有现象，做错了现象不对，你自己就能判别。

官方演示：实验地图页，上方是 3D 的 ESP32-S3 DevKitC-1 与逐个点亮的部件，下方是按主题分组的全部实验

每个实验先在浏览器里跑一遍

一个实验就是一屏：目标是什么、用哪几个引脚（在实时引脚图上标出来）、怎么接线、烧录用哪条命令、步骤可以逐条勾选，以及一个模拟结果的模拟器。最像「动手」的部分是串口——你可以在模拟串口监视器里敲命令，比如 blink、sos、level，板子会像真的烧了固件那样回应，模拟的 LED 也跟着变化。

这一步的意义不在炫技，而在于把「我有没有做对」的判断提前。真的板子到了之后，你的心里已经有一份预期：敲这条命令应该出现什么，如果不出现，问题大概在接线还是固件。

官方演示：第 02 课，左侧是引脚图，右侧是接线预览与模拟串口监视器，敲入命令后模拟 LED 跟随变化

32 个实验怎么排的

实验按主题分成六组，从零开始一路往上：入门三个（搭建工具链、第一个程序、第一个电路），显示与输入两个（1.9 寸 TFT 屏与按键），Wi-Fi 三个（扫描与连接、用手机控制、联网与调用接口），RFID 与 NFC 八个（从 13.56MHz 场与卡片存储一路做到带发卡管理的门禁），蓝牙八个（广播、配对、手机 App、键盘、音频），声音八个（响度检测、击掌控制、录音、频谱、扬声器）。传感器那一组（温度、空气、I2C 运动）还挂在计划里。

这个排法的好处是每一组都自成一条上升曲线，你不必按顺序全做——想做蓝牙键盘就直接从 B 组进，缺的前置知识在入门三课里补。每个实验也都能跳到它在固件仓里对应的目录，看完讲解可以直接去看完整工程。

代码不是贴上去的，是拆开讲的

嵌入式教程最常见的失败点是代码：贴一大段 C++，新手看两行就放弃。这里的做法是给同一份固件配三种读法。

固件本身不是手抄进网页的，而是在构建时从配套的 esp-labs 仓库里取出来，所以你读到的就是实验真正烧进去的那份代码。想按顺序啃，用 Tour：它一次只推进几行，还会先让你猜下一步会发生什么，再给出答案；想知道程序怎么跑，用 Story：从 setup()出发，跟着调用一路走下去；只想搞懂某一行，用 Explore：点哪一行就解释哪一行。遇到新的 C++ 词汇，一次只冒出来三个，见过的会记进 phrasebook，后面不再重复解释。

官方演示：代码阅读器的 Tour 模式带猜一猜卡片，随后是 Story 模式跟踪 setup() 的调用

手册那一侧：只留造东西要用的部分

新增的 Datasheet 区是围着芯片本身做的，思路是「只留一个动手的人真正需要的那部分」。它包括：芯片速览，配一个从整块板子一路 3D 下钻到裸片的视角；每一个引脚以及它能干的活；32 个外设模块各占一页的图册；以及内存、时钟和电源模式。

两个细节值得单独说。一是引用：页面上的每条事实都标注了它在技术参考里的章节，点一下就在侧边的阅读器里打开那一节，而不是把你丢到一个几十 MB 的 PDF 里。二是 Read 模式：它把板子指南、模块数据手册、芯片数据手册和技术参考合成一本可以顺着读的书，带分节勾选和「继续读到哪」，读手册这件事第一次有了进度条。另外，随着你勾选实验步骤，你实际用到过的那些外设模块会在图册里亮起来。

官方演示：Datasheet 区的引脚页、外设图册与 ADC 模块页，点引用在侧边阅读器打开参考手册对应章节

还有几件顺手的东西

Meet the board 是块能转的 3D 开发板，六个标注点，点一个就点亮对应部件，并列出用到它的实验——想知道 USB 口旁边那排针是干嘛的，直接点。实验台日志记录当前板子上烧的是什么、以及执行过的每条命令，它是一份纯 JSON，放在 public/data 下，改数据不用重新构建。进度存在浏览器里，没有账号，勾选状态、上次打开的实验、选过的变体都记得住。零件库里有 42 张等轴测零件图，颜色全部来自设计 token，整套插画风格一致。

实验台日志和零件库这两处最实用：前者把「现在板子上是什么状态」变成可分享的事实，改 JSON 就能更新，不用重新构建；后者让你写讲义或做幻灯片时直接复用风格统一的零件插图，而不用自己画。

11 种语言，含简体中文、繁体中文、日文，以及从右往左整体镜像的阿拉伯语；任意链接后面加 ?lang=fr就能把法语版分享出去。它在 390 像素宽的手机上可用，有明暗两套主题，也尊重系统的减弱动效设置。

技术栈与本地跑起来

前端是 React 19.3 配 React Compiler、React Router 8.4（data 模式 + hash 路由）、TanStack Query 5.104、zod 4.6、three 0.186、i18next 26.4，TypeScript 开着 strict，构建用 Vite 8.3，依赖全部精确锁版本。课程是数据、模拟器是按需加载的小部件、实验台日志是运行时去取的 JSON，这个分工让加一个实验不需要动框架。

URL 用的是 hash 形式，比如 #/lessons/R3，所以路由不需要服务端配合重写规则，静态托管时放到任意子目录都能直接打开；课程内容按主题分成多个 chunk 按需加载，模拟器也是懒加载的小部件，第一次进入不会一次性拉下所有实验的代码。运行时取回来的实验台日志会用 zod 校验一遍再渲染，字段写错了会当场报错，而不是在页面上显示一个 undefined。

要在本地跑，需要 Node 24.14 以上和 pnpm 11（corepack enable会给到你锁定的版本）。因为代码阅读器要读固件，官方建议把 esp-labs 和 esp-labs-web 两个仓库并排克隆，然后 pnpm install加 pnpm dev，服务起在 5180 端口。没有那份固件也不影响其余部分——课程、模拟器、实验台日志照常，只是代码阅读器没有内容可显示；想改指向就设 FIRMWARE_DIR。日常开发有三个命令值得记住：pnpm check一次跑完类型检查、lint 和测试，pnpm build出静态包（相对路径，放哪个目录都能服务），pnpm preview本地预览产物。

三类人收益最明显。第一类是刚入门、还没买板子的人：先用模拟器把概念过一遍，再决定要不要投入硬件。第二类是在教别人的人——培训班讲师、社团负责人、给孩子讲硬件的家长：课程本身就是可勾选的步骤清单，实验台日志能当教案的记录用。第三类是从别的平台转过来、已经会写代码但不熟这块芯片的人：直接跳到外设图册和你关心的实验，比通读手册快得多。

反过来，如果你已经把 ESP-IDF 用得很熟、只是想查某个寄存器的取值，那这份指南对你偏浅，直接查官方资料更快。

要注意的地方

第一件是许可证：仓库目前没有标注开源许可证，GitHub 的 License 一栏是空的，想二次分发或用在商业产品里，得先联系作者确认授权。

第二件是完成度：它非常新，32 个实验里 Wi-Fi 主题只到 W3（W4、W5 在计划中），传感器整组还标记为 planned。也就是说，冲着某个具体章节去的人，可能扑空。

第三件是部署方式有点绕：代码阅读器要在构建时把固件一起打包，而构建机上没有那份固件检出，所以线上的构建是关掉的，改由别的环境跑完构建再上传产物。你要自己部署时，会踩到同一个坑。

另外两点属于预期管理：手册正文是乐鑫的英文原文，只有标题跟随你的语言；它也不是乐鑫官方项目，引脚排布遵循 DevKitC-1 v1.0，而你板子上印的标签永远优先。

怎么开始

建议的顺序是：先在浏览器里把入门三个实验走一遍，尤其是 02 First circuit——敲几条命令，看模拟 LED 的反应，确认这套流程你能跟上。第二步再决定要不要买板子：如果 Wi-Fi、RFID、蓝牙、声音里有你真想做的主题，那这份指南值得配一块实物。真动手时按接线图接、照抄烧录命令，并把实验台日志记录起来，出问题回溯会快很多。第三步是被某段固件卡住时，别急着搜论坛，先用代码阅读器对着真实代码读一遍。

想参与也容易：改错别字或某一步写得不清楚，直接编辑对应主题的课程文件提 PR 就行，不需要碰 React；想加实验、加模拟器、加语言，官方也写了逐步的指引和要跑的检查。

仓库地址 agharsallah/esp-labs-web。对正在自学 ESP32-S3、又不想被手册劝退的人来说，它把「先看现象、再读代码」这条路径做得很完整。

#ESP32#