不靠谱的糖饼手头有一个项目要从 Node.js 服务不间断往 TDengine 写传感器数据，我第一反应是去翻官方文档里的“语言连接器”章节。结果发现 Node.js 这块内容更新得不算勤，社区里的帖子也经常是 Java、Python 刷屏，自己动手绕了些弯路才跑通。这篇就当作操作备忘整理出来，拿到的项目需求如果和我类似——技术栈是 Node.js，数据库侧是 TDengine 3.x——可以直接照着来。
我会尽量把翻车点写细。不是那种“官方文档复制一份”的教程，而是把连接器原理、API 选择、离线排错这些东西都摊开讲，至少让你在下班前能跑出第一批数据。
1. 动手写代码前，先想清楚连接器的定位和边界
很多人拿到 TDengine 就下意识想找一个大而全的 ORM，觉得数据库驱动就该像 Mongoose 一样把 model 层也做了，其实不是这么回事。TDengine 的定位是高性能时序数据库，语言连接器目前的主要任务就是：帮你把一条 SQL 或一堆参数发给服务端，再把返回结果翻译成你语言里方便处理的类型。它不负责业务建模，也不负责把某个对象自动映射成表结构。
从这个角度看，Node.js 连接器本质上就是个协议翻译层。你在 Node.js 进程里调 conn.query(...)，连接器把 SQL 语句按 TDengine 的网络协议打包，发给服务端的 6030 端口或者 6041 端口，然后读回响应、拆包，再转成数组或对象。这个链路里更靠近“能不能连上”的，是网络端口和鉴权，而不是 Node 的版本。
我建议你先记住三个端口：原生连接一般走 6030，REST 接口走 6041，taosExplorer 的 Web 界面走 6060。如果你用 taosExplorer 3.3.7.1 连不上数据库，先别怀疑浏览器或插件，很可能就是 6030 这个端口根本没开或者被防火墙拦了。这个问题后面我专门有一节来说，因为在实际项目里它占了连接故障的一大半。
TDengine 和 MySQL、PostgreSQL 另一个明显差异是：建表通常要带时间戳列，而且实际写入经常是几十万、上百万条的高频时序数据。你拿 Node.js 连 TDengine，如果还用传统数据库的写法一条一条 insert，必然要挨打。第 5 节我会把批量写入和参数组织的逻辑一并讲，那才是实践里的核心点。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备清单：Node 版本、TDengine 实例与连通性检查
2.1 Node.js 版本怎么选才稳
先聊版本。Node.js 官方当前推荐偶数版本进入 LTS，比如 20、22，非特殊需求不建议用奇数开发版，更别提前沿版本。网上你可能会看到类似 error installing 24.20.0: node.js v24.20.0 is not yet released or is not available 的报错，这种场景多半是你用了 nvm、n 这类版本管理工具，手动指定了一个远端版本列表里还没同步的版本号。解决办法很简单：先执行 nvm ls-remote 确认版本真的存在，再安装，不要照着某篇旧博客手输一个未来版本号。
做 TDengine 的 Node.js 连接器开发，我实测用 Node.js 22 LTS 最省心。TDengine 官方 npm 包在某些版本对 Node 版本有下限要求，比如提示需要 Node.js 22.13 以上，但你如果选了个非 LTS 预览版，又可能碰到原生模块编译不兼容。建议统一用 LTS，装一次版本管理器，例如 Mac/Linux 下用 nvm，Windows 下用官方安装包或 nvm-windows。
如果你问 Windows 7 能不能装 Node.js 18，我可以直说：不太建议。Node.js 官方很早就停止支持 Windows 7，而 TDengine 3.x 的生态也尽量往现代系统上靠。开发机如果还是 Win7，系统层面的 TLS、网络库都可能出问题，不如直接在虚拟机里跑 Linux 环境，反而少很多坑。
2.2 把 TDengine 起起来并确认服务正常
假设你本地已经装好了 TDengine 3.3.7.1 或同期的 3.x 版本。启动服务后，第一件事不是开编辑器，而是先在命令行里确认数据库本体是活的。Linux/Mac 下直接执行：
bash复制taos
进入 taos shell 后执行：
sql复制SELECT server_version();
能返回 3.x.x.x 之类的版本号，说明服务端进程没问题。接着再创建一个最简单数据库，验证磁盘和权限没毛病：
sql复制CREATE DATABASE IF NOT EXISTS test_demo;
USE test_demo;
CREATE TABLE IF NOT EXISTS t1 (ts TIMESTAMP, val FLOAT);
INSERT INTO t1 VALUES (NOW, 1.23);
SELECT * FROM t1;
如果这几条语句都能跑通，说明 TDengine 本体安装成功。这一步别嫌多余，很多 Node.js 连接器调不通的案例，最后排查下来不是连接器问题，而是服务端压根没起来。
在 TDengine 3.x 里，你也可以用 taosExplorer 来做可视化管理。默认通过 http://localhost:6060 打开，登录后能看到监控、SQL 终端、数据查看等功能。它的作用有点像 MySQL 的 phpMyAdmin，排查连接问题、查看表结构时非常好用。
2.3 验证 REST 端口与原生端口是否可达
接下来需要验证 Node.js 进程要访问的网络端口。有两种连