node.js必须独立安装且vscode内置终端能识别才算真正可用；需在vscode终端执行node -v验证，失败则macos/linux检查~/.zshrc路径导出并完全退出重开，windows须重装时勾选add to path或手动添加系统环境变量。
确认 Node.js 真正在 VSCode 里可用
VSCode 不自带 node，它只是编辑器。你在终端敲 node -v 成功 ≠ VSCode 内置终端能用——这是最常卡住的第一步。
常见错误现象：command not found: node 出现在 VSCode 的 Ctrl + ` 终端里，但系统终端正常。
- macOS/Linux：检查
~/.zshrc或~/.bash_profile是否导出了 Node 路径（比如export PATH="/usr/local/bin:$PATH"），然后完全退出 VSCode（Dock 右键「退出」，不是关窗口），再用图标重开 - Windows：安装 Node.js 时必须勾选
Add to PATH；若漏了，手动把C:\Program Files\nodejs\加进「系统环境变量」的Path，并重启 VSCode 进程（任务管理器杀掉所有Code.exe） - 验证方式：重启后，在 VSCode 内置终端执行
which node（macOS/Linux）或where node（Windows），输出路径应指向你安装的 Node 目录
安装 serialport 并处理原生模块编译问题
serialport 是纯 JavaScript 封装，但底层依赖 C++ 原生模块（@serialport/bindings），Node 版本一换、架构一变，就容易编译失败或运行报错。
常见错误现象：Error: The module ... was compiled against a different Node.js version，或 Cannot find module '@serialport/bindings'。
- 先确保用的是 LTS 版 Node（如 v20.15.x），避免用 Current 版；可通过
node -v确认 - 安装命令必须带
--build-from-source强制本地编译：npm install serialport --build-from-source - 如果报
gyp ERR!，macOS 需先装 Xcode Command Line Tools：xcode-select --install；Windows 需装 Visual Studio Build Tools（勾选「C++ build tools」） - ARM Mac（M1/M2/M3）用户注意：不要用 Rosetta 启动 VSCode，否则可能因架构不匹配导致绑定加载失败
在代码中正确打开串口并处理权限/路径问题
串口设备路径和访问权限是跨平台最不一致的地方，硬编码 /dev/ttyUSB0 或 COM3 很可能直接报错。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
常见错误现象：Error: No such file or directory, open '/dev/ttyUSB0'，或 Windows 下提示 Access is denied。
- 先用
serialport自带工具查设备：npx @serialport/list（需已全局或本地安装serialport），输出类似{ path: '/dev/cu.usbserial-1420', vendorId: '0x1a86', productId: '0x7523' } - macOS：优先用
/dev/cu.*而非/dev/tty.*，后者可能被系统占用；若提示权限拒绝，执行sudo chmod 666 /dev/cu.usbserial-1420（临时方案，生产环境建议加用户到dialout组） - Windows：设备管理器里看 COM 编号（如 COM4），代码中写死
'COM4'即可；若报 Access denied，关闭所有其他串口工具（如 Arduino IDE、Putty） - 代码示例（带错误兜底）：
const { SerialPort } = require('serialport');<br>const port = new SerialPort({<br> path: '/dev/cu.usbserial-1420', // 替换为 list 查到的真实路径<br> baudRate: 9600,<br> autoOpen: false<br>});<br><br>port.open(err => {<br> if (err) {<br> console.error('串口打开失败:', err.message);<br> return;<br> }<br> console.log('串口已打开');<br>});
调试时数据收发不同步、乱码或丢包
串口通信不是 HTTP，没有自动重试和粘包处理，Node.js 默认以 Buffer 接收，不做解码会看到 <buffer></buffer> 这类输出，而非字符串。
常见错误现象：收到数据是乱码、只收到一半、data 事件触发多次但内容被截断。
- 接收端务必用
Readable流方式解析，而不是依赖单次data事件：port.on('data', data => {<br> console.log('原始 buffer:', data);<br> console.log('转字符串:', data.toString()); // 默认 utf8<br>}); - 发送前确保目标设备已就绪，加简单延时或握手协议（比如等单片机回传
READY再发指令） - 波特率必须两端严格一致；51 单片机常用 9600，但若晶振不准（如 11.0592MHz），实际波特率会有偏差，可微调
baudRate或改用 115200 提高容错 - 避免在
data回调里做耗时操作（如文件写入、网络请求），否则缓冲区堆积导致丢包；高频数据建议用parser模块（如@serialport/parser-readline）分帧
真正麻烦的从来不是写几行 port.write()，而是设备路径动态变化、Node ABI 版本漂移、以及串口线松动导致的偶发通信中断——这些没法靠重跑代码解决，得靠 npx @serialport/list 多查、用 ls -l /dev/cu.* 看权限、拔插线确认物理连接。
