1. Wokwi 到底是什么为什么本地跑这么香1.1 一句话说清 Wokwi 的定位Wokwi 是一个基于浏览器的开发板仿真平台支持 Arduino Uno、Mega、ESP32、ESP32-C3、Raspberry Pi Pico、STM32、ATtiny 等一系列常用开发板。你不需要真的下单买一块板子也不用等快递、接杜邦线、担心烧板子只要打开网页或者本地拉起模拟器就能写出能跑的固件再通过虚拟串口看到实时日志。我最早接触它是在教朋友入门物联网的时候。朋友买了一块 ESP32结果环境没配好板子吃灰半个月。后来我让他先上 Wokwi 把代码逻辑跑通再用真板子验证效率一下子高了很多。可以说Wokwi 把学习开发板这件事的门槛从先花几十到上百块买硬件降到了只要有台电脑。这次要聊的本地运行 Wokwi核心价值在于把整个仿真的工程目录、编译链路、版本管理都放到本地。网页版适合随手验证但一旦项目复杂、要接自己的库、要长期维护本地跑才是舒服的状态。1.2 本地运行和网页版的真实差异很多人问网页版不是挺好用的吗为什么非要本地运行网页版确实够方便打开 wokwi.com选一个模板直接写代码。但实际用下来你很快会遇到几个很烦的痛点项目文件散在云端想用 Git 管理要手动导出再导回编辑器用来用去还是网页里那套不习惯自己的快捷键和主题想把自己本地写好的库、头文件、配置文件塞进项目网页版传文件麻烦工程大了之后网页加载和模拟器响应会有肉眼可见的卡顿本地运行的方案就解决了这些项目就是一个普通目录直接用 VS Code 打开代码、编译、仿真、串口输出全都走本地进程。目录里放什么文件、用哪个版本的库完全由你说了算。一个容易误解的点所谓本地运行并不是彻底断网离线。Wokwi 的模拟器首次启动和登录授权仍然需要访问官方服务但日常工作流是本地主导而不是像网页版那样所有操作都压在浏览器里。把本地理解成本地工程管理 本地编译 本地启动模拟器进程更准确。2. 环境准备5 分钟配齐本地仿真工具箱2.1 VS Code 与 Wokwi 扩展安装本地运行 Wokwi 目前最成熟的方案就是 VS Code 扩展官方名字直接搜 Wokwi 就能找到。安装步骤没什么玄学打开 VS Code进入扩展市场搜索 Wokwi选官方出品的那个作者是 Wokwi点击 Install装完重启一下窗口让扩展激活装完之后你会多出几个命令都在命令面板里快捷键 CtrlShiftP 或者菜单栏 Terminal - Run Task 旁边那个命令面板入口。常用的是Wokwi: Start Simulator启动仿真Wokwi: Open Diagram打开电路图 JSONWokwi: Stop Simulator停止仿真这里有个细节值得注意扩展本身只是图形化外壳真正的模拟器跑在 Wokwi 提供的 CLI 程序里。扩展会在你第一次使用的时候去查找或者自动安装 wokwi-cli。如果安装过程网络不稳定后面启动仿真器就会报找不到 CLI 的错。遇到这种情况直接去官方 GitHub 仓库下载对应平台的 CLI 可执行文件再把它所在目录加到系统 PATH 里重开 VS Code 即可。注意本地项目路径尽量不要带中文和空格。我之前曾把项目放在桌面/Wokwi 学习目录里结果 CLI 一直起不来各种奇怪报错。后来改成全英文路径一次通过。2.2 Arduino CLI 与系统依赖准备Wokwi 能仿真很多板子但这些板子的固件还得靠真实工具链编译。如果你写的是 Arduino 代码就需要本地有 Arduino CLI 或者一份完整的 Arduino IDE。为什么 Wokwi 不自己内置编译器因为内部集成编译器会带来巨大的体积和维护成本还要跟踪各开发板工具链的更新。让编译走本地统一工具链既保证和真实硬件编译行为一致也方便你本来就在本地做开发的人复用现有环境。安装 Arduino CLI 最省事的办法Windows直接下载官方 zip 包解压后把 arduino-cli.exe 所在目录加进 PATHLinux/macOS官方也提供安装脚本或者用包管理器安装Homebrew 直接 brew install arduino-cli装完在终端里敲一下 arduino-cli version能输出版本号就说明没问题。还有一个隐藏需求如果之前机器上没有装过 Arduino 内核第一次编译某个板子比如 ESP32时Arduino CLI 会自动下载对应芯片的编译工具链。这个下载通常得跑几分钟而且在国内网络环境下可能很慢甚至失败。我的经验是提前手动执行几条命令把核心包拉好arduino-cli core update-index arduino-cli core install esp32:esp32这样后面 Wokwi 启动编译的时候就不用临时拉那一大坨工具链了。2.3 登录令牌与网络要求必要说明Wokwi 扩展第一次启动仿真器时会要求你登录 Wokwi 账号并生成一个 CLI token。流程是命令面板里选择 Wokwi: Start Simulator会弹出提示让你在浏览器中打开 wokwi.com登录后页面会显示一串令牌字符串把它复制回 VS Code 窗口粘贴。这个 token 是模拟器进程跟官方服务通信的凭证不是密码但也不要顺手贴到博客、开源仓库里。Wokwi 官方文档也明确提醒过这一点。另外我实际测下来启动模拟器的时候当前网络环境必须能正常访问 Wokwi 的 API 才会通过授权校验。局域网、防火墙很严格的办公网络可能会卡在这一步。如果公司网络把这些外部域名拦了本地 Wokwi 基本跑不起来不是代码问题是环境网络问题。3. 核心机制拆解diagram.json、固件代码与仿真器如何配合3.1 工程目录与三件套一个本地 Wokwi 项目缩到最小也是三样东西diagram.json电路连接描述文件声明了用了哪些元件、引脚怎么接固件代码文件Arduino 项目就是 .ino 文件ESP-IDF 项目就是 C/C 源文件具体看你要仿真什么wokwi.toml可选告诉 Wokwi 用哪个固件文件启动我见过不少新手一上来就把所有代码堆在一个 main.ino 里然后 diagram.json 里只放了一块开发板能跑是能跑但完全没有仿真电路的灵魂。Wokwi 之所以能成为云实验室核心就在于 diagram.json 能描述完整电路LED、电阻、传感器、显示屏、按键全都能画出来模拟器会按照这个电路来驱动引脚上的逻辑。wokwi.toml 长得像这样[firmware] elf build/esp32.elf如果项目里有多个代码文件这个文件能指定到底哪个是入口。Arduino 项目大多不用特别配置Wokwi 会自动找同目录下的 .ino 文件。3.2 diagram.json 电路描述语法diagram.json 本质上是一份 JSON 格式的电路描述由三块组成parts元件表、connections引脚连接、serialMonitor串口监视器配置可选。拿一个最经典的ESP32 点亮 LED来说diagram.json 长这样{ version: 1, author: your-name, editor: wokwi, parts: [ { type: wokwi-esp32-devkit-v1, id: esp, top: 0, left: 0, attrs: {} }, { type: wokwi-led, id: led1, top: 0, left: 300, attrs: { color: red } }, { type: wokwi-resistor, id: r1, top: 0, left: 150, attrs: { value: 220 } } ], connections: [ [ esp:13, r1:1, red, [] ], [ r1:2, led1:A, gold, [] ], [ led1:C, esp:GND.1, black, [] ] ] }连接数组的每一行格式是[起点, 终点, 颜色, 可选参数]。颜色只是画图时好看不参与逻辑。每个元件的引脚名要去 Wokwi 对应元件文档里查ESP32 开发板的引脚一般是esp:13这种 GPIO 编号GND 则是esp:GND.1、esp:GND.2这样的多路地线。很多新手会被引脚名搞晕。其实方法很简单在 VS Code 里打开 diagram.json按 CtrlSpace扩展会自动提示当前元件支持的所有引脚。或者直接去 wokwi.com/elements 找元件文档里面引脚表列得很清楚。3.3 仿真器工作原理和限制Wokwi 的模拟器不是简单的代码跑一遍 假装有 LED它内部实现了芯片级的外设模拟GPIO 高低电平、UART 收发、I2C/SPI 时序、ADC 转换甚至一部分 WiFi 功能比如用包管理工具模拟 WiFi 连接和 HTTP 请求。这意味着你在代码里 digitalWrite 一个引脚模拟器会真的在电路图上把那个引脚的连接线状态更新LED 元件根据接入的电阻和电压算出是否点亮亮度还有真实的比例关系。这种感觉很接近拿一块真实板子去调电路。但它的限制同样明确模拟的是芯片关键外设行为不是 100% 真实的硅片时序某些微妙时序边沿和真板子有差异部分高级外设例如 ESP32 的蓝牙、某些模拟外设支持不完整传感器库不全不是市面上每种传感器都有现成元件连接线没法仿真杜邦线接触不良这种玄学问题所以正确的用法是学习逻辑、调通程序、验证模块交互用 Wokwi最终上板子之前再留出时间做真实硬件验证。它不能完全替代真板但能把你在真板上排查逻辑错误的时间压缩很多。4. 实操从零点亮一颗 LEDESP32 示例4.1 创建项目结构与代码废话不多说我按自己常用的目录习惯来搭一个 ESP32 LED 闪烁项目。mkdir wokwi-esp32-blink cd wokwi-esp32-blink在这个目录里先创建一个 src 目录放固件代码mkdir src然后在 wokwi-esp32-blink 根目录下创建 diagram.json用第三节里那份 JSON 就行。接着在 src 下创建 main.ino#define LED_PIN 13 void setup() { pinMode(LED_PIN, OUTPUT); Serial.begin(115200); Serial.println(Hello from Wokwi!); } void loop() { digitalWrite(LED_PIN, HIGH); delay(500); digitalWrite(LED_PIN, LOW); delay(500); }注意 Arduino 项目默认要求 .ino 文件名和所在目录名一致。这里我把固件放在 src/main.ino但 if 目录内只有一个 .ino 文件Wokwi 和 Arduino CLI 通常也能正确识别。如果你放多个 .ino 文件就要保证其中一个和目录同名的文件存在否则编译会报错。4.2 启动仿真与串口日志代码和电路图都齐了之后按 F1输入 Wokwi: Start Simulator。第一次启动会有几步交互弹出登录授权按浏览器提示粘贴 token扩展检查 wokwi-cli没有就自动装Arduino CLI 开始编译固件编译成功后打开一个仿真窗口左侧是电路图右侧是串口监视器如果一切正常你会在电路图上看到 ESP32 板子、电阻和 LED绿色连线按 diagram.json 里的定义连好。串口监视器里会滚动输出 Hello from Wokwi!LED 则以 1Hz 频率闪烁。这里我特意加了 Serial.println因为很多人第一次跑本地 Wokwi 会忽视串口输出窗口以为没反应。串口输出是调试嵌入式程序最有用的手段在 Wokwi 里也是实时刷新跟真实板子连着串口的感觉几乎一样。4.3 断点、调试与交互玩法Wokwi 扩展一个隐藏优势是支持调试。在代码里打断点然后启动仿真时选择 Wokwi: Debug 之类的方式具体入口在扩展的菜单或命令里也可以直接按 F5 看 VS Code 的调试配置模拟器会像调试本地程序一样停在断点处变量、调用栈都能看。还有一个很爽的交互功能仿真过程中你可以在电路图上点击 LED、按键、传感器来模拟物理操作。比如放一个按键元件运行的时候鼠标点它相当于真实按下去代码里读到的引脚电平会立即变化这个过程不需要改任何代码。这意味着你能在纯软件环境里完整演练一套按键控制 LED 串口打印的交互逻辑这在网页版也能做但本地大屏调试起来更顺手尤其调试多文件项目时。5. 常见问题排查与避坑实录5.1 编译失败的原因本地 Wokwi 编译失败九成不是代码问题而是工具链问题。我整理了几个高频场景现象原因处理办法报错找不到 arduino-cliCLI 没安装或不在 PATH重新安装并把路径加进 PATH重启 VS Code编译时下载工具链卡住芯片核心包未预装提前执行 arduino-cli core install 对应核心编译报 No such file or directory项目路径含中文或空格项目挪到纯英文路径找不到头文件本项目依赖的第三方库没安装用 arduino-cli lib install 装库或把库目录放进去.ino 文件入口冲突目录下有多个 .ino 且没有同名入口文件规范文件命名保留一个和目录名相同的入口编译日志默认在 VS Code 终端里别只看红字往上翻几条报错信息里的路径会明确告诉你到底是编译链还是代码的锅。5.2 仿真器假死、一直加载本地仿真器启动后白屏、一直转圈或者直接没反应我遇到过几次主要来自这几个方面token 过期或失效重新走一遍登录流程wokwi-cli 版本太旧扩展和 CLI 版本不匹配去 GitHub 仓库拉最新 release 替换端口冲突本地有其他程序占用了模拟器要用的端口杀掉冲突进程再试浏览器缓存问题扩展内置的仿真界面有时候表现像浏览器清一下 VS Code 窗口缓存或重开窗口最粗暴有效的办法停掉扩展重新打开。大部分假死是进程状态错乱重启就能解决。提醒Windows 上如果开了代理类网络软件又加了系统级过滤可能会导致模拟器连接 API 失败。这种情况不是 Wokwi 的问题先把网络环境恢复干净再试。5.3 串口监视器没有输出代码烧进去板子在图上跑但串口监视器空荡荡是最容易让新手懵的场景。先从代码本身查有没有 Serial.begin波特率跟右侧串口监视器的波特率设置是否一致很多例程用 115200但有人手动把监视器调到 9600自然看不到正常输出。再查启动状态有些开发板进入仿真前默认走的就是 UART 日志如果启动时除了代码输出还有 ROM 启动日志说明串口链路是通的。真的一点输出都没有试着把代码里的 Serial.println 放到 setup 最前面排除代码执行到串口初始化之前就没往下走的可能。还有一个坑部分 ESP32 型号的 USB 串口和 UART0 在仿真里不完全是同一个映射用打开后自动选定的那路即可不要强行改到别的串口。5.4 关于已修正这个标题这个标题里有已修正三个字我多说一句。网上很多 Wokwi 相关的旧教程问题是版本太老步骤停留在网页版或者是把 Wokwi 当成完全离线工具误导新人一顿乱装。实际从 2023 年以后Wokwi 官方逐步把重心放到了 VS Code 扩展和 CLI 这条本地化路线上从在线工具变成了可以嵌入日常工作流的仿真平台。如果你之前按某些旧教程配过发现不对劲就直接把项目目录清干净按本文的步骤重新搭一次。所谓修正就是跟上一个正确、可复现的版本而不是在旧思路里打补丁。6. 本地 Wokwi 的进阶玩法与扩展思考6.1 自定义芯片仿真不是只能模拟现成元件Wokwi 最被低估的能力是自定义芯片。官方提供了一套基于 JavaScript 的 API允许你写一个 TS/JS 脚本自己实现一个 Wokwi 里没有的元件定义它的引脚行为、时序逻辑、甚至响应用户交互事件。这意味着什么你在真实项目中用到一款小众传感器Wokwi 没有现成模型你可以按数据手册把它的关键行为简化实现出来先用仿真验证固件逻辑等真板到了再验证真实硬件。让仿真平台从玩具库变成了你自己设计的元件的测试台。6.2 与 CI/CD 结合仿真变成自动化测试工具本地跑 Wokwi 还能接进 Continuous Integration 流程。你在 GitHub Actions 里安装 wokwi-cli然后跑编译加仿真通过一个测试脚本驱动模拟器的输入检查串口输出是否符合预期。Wokwi 本身就是嵌入式开发的软件在环测试能让开发者不用买一堆板子就完成大部分逻辑回归测试。这是很多人没往那边想的方向但我个人建议有条件的话试一下。当前嵌入式测试往往依赖真实硬件跑一次手忙脚乱而 Wokwi 本地化之后至少在单元级别的功能验证上完全有能力承担一部分重复劳动。6.3 如何把仿真技能迁移到真实开发板最后说点实在的。本地 Wokwi 用得再多它也只是第一站。你接自己的真板子时会面临几个 Wokwi 环境里没有的问题驱动安装CH340、CP2102 这类 USB 转串口芯片在没装驱动前根本连不上板卡型号差异比如同是 ESP32开发板引脚排布也有区别电源和接线错误Wokwi 里不会烧东西真板会真实传感器时序抖动仿真太干净了真环境各种毛刺我的建议是用 Wokwi 跑通逻辑把注意力集中在代码结构、外设时序、串口协议这些核心知识上。等上真板时你心里有数知道大概率是硬件问题还是逻辑问题不会因为一个小问题就怀疑人生。本地运行 Wokwi 这件事本身不难难的是彻底理解它到底替你解决了什么。它把调试开发板程序这个通常需要硬件和耐心的事变成了一件随时随地可以练的基本功。如果你正考虑买开发板但还没动手或者买了板子却配不好环境我强烈建议先用本地 Wokwi 把代码层面的东西跑熟。等到真要入手硬件的时候你已经能把自己的程序烧上去直接验证那种顺畅感远比从零折腾舒服得多。
