1. 为什么在 Ubuntu 上折腾 Esp32S3 的 Arduino 环境如果你手上有一块 Esp32S3 开发板想在 Ubuntu 桌面上写 Arduino 风格的代码大概率会经历这样一个过程先装 Arduino IDE用着用着发现多文件管理很别扭代码提示时有时无窗口一多就乱。于是转向 vscode结果发现 vscode 本身不认识.ino串口也找不到编译报一堆头文件缺失。这套链路的核心其实是 arduino-clivscode 只是套在外面的一层壳把编译、上传、串口监视这些动作图形化了。这篇内容面向的是在 Ubuntu 桌面从零搭建 Esp32S3 Arduino 开发链路的同学包括 vscode 装 Arduino 扩展、arduino-cli 安装 esp32 核心与库、串口权限处理、编译上传验证最后给出一份可复制的 settings.json 与 arduino-cli 配置骨架。同时我会把 TaoToken 统一 Key 接入 AI 辅助编码的验证动作也串进来让你在写代码卡壳时能直接调模型对话而不是切来切去。整条链路跑通后你得到的是一个能编译、能上传、有语法提示、还能顺手问 AI 的工作区。需要提前说明的是Esp32S3 的核心包体积不小第一次安装会下载几百 MB网络环境正常的话耐心等就行。串口权限是 Ubuntu 上最容易卡住新手的点后面会单独讲。TaoToken 在这里的角色是给 AI 辅助编码提供一个统一的 Key 和 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 不带多余参数。2. TaoToken 前置统一 Key 与 API 通道准备在开始配 arduino-cli 之前先把 AI 辅助这条线准备好这样后面写代码遇到报错可以直接问。TaoToken 的作用是提供一个统一的 Key让你通过一个 API 通道访问模型对话能力不用每个模型单独申请。你需要做的是拿到 Key并确认 API 地址。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在里面找到 API Keys 页面路径是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。新建一个 Key复制出来保存好这个 Key 就是后面所有 AI 调用的凭证。API 的基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接写进配置即可。如果你只是想先验证模型能不能通可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息试试。如果你打算长期用 AI 辅助编码甚至跑 Agent 类的工具可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。这里要提醒一句Key 不要硬编码进公开仓库建议放在环境变量或者本地不提交的配置文件里。后面我会给一个 settings.json 骨架里面涉及 AI 通道的部分用占位符表示你替换成自己的 Key 即可。3. 可复制配置arduino-cli 安装与 esp32 核心3.1 安装 arduino-cliUbuntu 下安装 arduino-cli 最省事的方式是用官方脚本。打开终端执行curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh这个脚本会把 arduino-cli 装到当前目录的bin下。如果你希望全局可用把它移到/usr/local/binsudo mv bin/arduino-cli /usr/local/bin/然后验证arduino-cli version能输出版本号就说明装好了。如果你习惯用包管理器也可以从 GitHub Releases 下载对应 Linux 64bit 的 tar.gz解压后把二进制放进 PATH。我实测下来脚本方式最不容易出错。3.2 初始化配置并添加 esp32 板管理地址arduino-cli 需要一个配置文件来记录板管理地址和库路径。先执行初始化arduino-cli config init默认会生成在~/.arduino15/arduino-cli.yaml。接着把 Esp32 的板管理地址加进去arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json然后更新索引arduino-cli core update-index这一步会拉取板子列表网络正常的话几十秒完成。3.3 安装 esp32 核心Esp32S3 属于 esp32 核心包安装命令arduino-cli core install esp32:esp32这个包比较大会下载编译工具链和库耐心等。装完后可以用下面的命令确认arduino-cli core list你应该能看到esp32:esp32以及版本号。如果这一步卡住或者报网络错误多半是板管理地址没加对回头检查arduino-cli.yaml里的additional_urls。3.4 串口权限处理Ubuntu 下普通用户默认没有串口读写权限插上 Esp32S3 后/dev/ttyUSB0或/dev/ttyACM0会提示 permission denied。解决办法是把当前用户加入dialout组sudo usermod -aG dialout $USER执行完必须注销重新登录或者重启组权限才会生效。验证方式groups看到dialout就对了。然后插上板子用arduino-cli board list应该能看到端口和对应的板子信息。如果端口没出现检查 USB 线是不是只供电不传数据换一根试试。3.5 vscode 扩展与 settings.json 骨架vscode 里需要装两个扩展C/C 和 Arduino。C/C 提供底层语法支持Arduino 扩展负责调用 arduino-cli。装完后打开设置搜索 Arduino把Arduino: Use Arduino CLI勾上这样它就走 cli 而不是老 IDE。下面是一份可复制的settings.json骨架放在工作区的.vscode/settings.json里{ arduino.useArduinoCli: true, arduino.path: /usr/local/bin, arduino.commandPath: arduino-cli, arduino.logLevel: info, arduino.enableUSBDetection: true, arduino.defaultBaudRate: 115200, C_Cpp.default.includePath: [ ${workspaceFolder}/**, /home/你的用户名/.arduino15/packages/esp32/tools/esp32-arduino-libs/idf-release_v5.1-3662303f31/esp32s3/include/** ], C_Cpp.default.defines: [ ARDUINO200, ESP32S3 ], C_Cpp.default.intelliSenseMode: linux-gcc-x64 }注意把你的用户名换成实际用户名idf-release那串版本号以你本地实际安装的为准可以用ls ~/.arduino15/packages/esp32/tools/esp32-arduino-libs/查看。includePath 加上之后语法提示丢失和爆红问题基本就解决了。如果你想把 AI 辅助编码的通道也写进配置可以单独放一个不提交的本地文件比如.vscode/taotoken.local.json{ api_base: https://taotoken.net/api, api_key: 你的_TaoToken_Key, default_model: 按控制台可选模型填写 }这个文件加到.gitignore里避免 Key 泄露。4. 验证请求编译上传与 AI 通道连通4.1 创建项目并写测试代码新建一个文件夹比如esp32s3_blink进去后用 vscode 打开。按CtrlShiftP输入 Arduino选择Arduino: Initialize然后输入项目名选择板子类型ESP32S3 Dev Module。扩展会生成.ino文件和.vscode配置。写一段最简测试代码void setup() { Serial.begin(115200); delay(1000); Serial.println(boot ok); } void loop() { Serial.println(hello esp32s3); delay(1000); }4.2 编译与上传在 vscode 底部状态栏选择串口然后点验证按钮对勾编译。第一次编译会久一点因为要编译核心库。编译通过后点上传按钮右箭头。上传成功后打开串口监视器波特率选 115200应该能看到每秒输出一行hello esp32s3。如果你更喜欢命令行也可以直接arduino-cli compile --fqbn esp32:esp32:esp32s3 ./esp32s3_blink arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32s3 ./esp32s3_blink--fqbn是板子标识Esp32S3 对应esp32:esp32:esp32s3。端口按实际改。4.3 验证 TaoToken AI 通道AI 通道的验证很简单用 curl 发一条请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_TaoToken_Key \ -H Content-Type: application/json \ -d { model: 按控制台可选模型填写, messages: [{role: user, content: 用一句话说明 Esp32S3 的 Arduino 核心包叫什么}] }如果返回里有正常的文本内容说明 Key 和 API 通道都通了。之后你在 vscode 里写代码遇到编译报错可以把报错贴到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 让它帮你定位。长期高频用的话Coding Plan 会更合适。5. 本篇常见错排查5.1 arduino-cli board list 看不到端口先确认板子插上后系统有没有识别到 USB 设备lsusb dmesg | tail -20如果dmesg里没有出现 tty 相关行多半是线的问题或者板子没进下载模式。Esp32S3 有些板子需要按住 BOOT 再插线。另外确认自己在dialout组里重新登录过。5.2 编译报头文件找不到典型报错是fatal error: WiFi.h: No such file or directory。这通常是核心包没装全或者 includePath 没配。先确认arduino-cli core list有esp32:esp32才行。然后检查settings.json里的 includePath 路径是否真实存在版本号是否对得上。路径里用户名写错是最常见的。5.3 语法提示爆红但能编译这是 vscode 的 C/C 扩展没找到头文件和实际编译无关。解决办法就是第 3.5 节里的 includePath 配置。改完 settings.json 后按CtrlShiftP执行C/C: Reset IntelliSense Database再等它重新索引。5.4 上传时报权限错误报错类似Permission denied: /dev/ttyUSB0。回到 3.4 节确认dialout组已生效。临时办法是sudo chmod 666 /dev/ttyUSB0但每次插拔都要重来不推荐。5.5 TaoToken 请求返回 401先检查 Key 有没有复制完整前后有没有多余空格。再确认请求头是Authorization: Bearer 你的Key注意 Bearer 后面有一个空格。如果还是 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认 Key 状态是否正常有没有被禁用或额度用完。5.6 串口监视器乱码波特率和代码里Serial.begin不一致是最常见原因。代码写 115200监视器也要选 115200。另外 Esp32S3 有些板子复位后会打印一段 boot 日志那段乱码是正常的等它进入你的 loop 输出就好。6. 把 AI 辅助接进日常编码流程环境跑通之后日常开发里最影响效率的其实是两件事一是编译报错定位二是库函数记不住。前者可以把报错直接丢给模型对话后者可以让它给你一段示例。TaoToken 的统一 Key 在这里的价值是你不用为每个模型单独配一套凭证一个 Key 走同一个 API 地址 https://taotoken.net/api 就行。如果你只是偶尔问几句模型对话页面足够。如果你在 vscode 里想更顺滑地接入可以把 API 地址和 Key 配到支持自定义端点的 AI 编码插件里让它走 TaoToken 通道。长期做 Esp32S3 项目、频繁让 AI 帮你写驱动或排错的可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有不同语言的调用示例。最后给一个实用习惯每次新建 Esp32S3 项目先把.vscode/settings.json从模板复制过去includePath 里的版本号用脚本自动填省得每次手改。串口权限一次性配好后面插拔都不用 sudo。AI 通道的 Key 放本地不提交的文件用的时候读环境变量。这套流程跑顺之后Ubuntu 下开发 Esp32S3 的体验会比 Arduino IDE 舒服不少。