Neo4j Aura作为官方托管的图数据库服务，省去了自建服务器的麻烦，但它和本地部署的Neo4j在使用方式上有一个关键差异：Aura只接受加密连接，URI必须使用neo4j+s协议。很多开发者直接把本地开发时的bolt://localhost:7687改个地址就拿去连Aura，结果连证书校验都过不了。这篇文章会从零开始，讲清楚用Node.js连接Aura实例的每个环节，包括驱动创建、会话管理、连接池调优和常见的报错排查。
一、安装驱动与理解Aura的连接协议
Neo4j官方为Node.js提供的驱动包是neo4j-driver，安装非常简单，在项目目录下执行npm命令即可。需要注意的是，这个包从4.x版本开始对Aura的兼容性已经非常好，建议直接安装最新版本，避免老版本驱动在新版Aura上的握手问题。
npm install neo4j-driver
连接Aura之前，先要弄清楚它的URI格式。Aura控制台给出的连接地址长这样：neo4j+s://xxxxxxxx.databases.neo4j.io。这里的neo4j+s表示使用TLS加密的Bolt协议，这是Aura唯一支持的连接方式。如果你写成neo4j://或bolt://，驱动会尝试用普通方式握手，服务端会直接拒绝。区别在于：neo4j+s是全链路加密并且默认校验证书，而neo4j+ssc虽然也加密但不校验证书，后者一般只用于自签名证书的私有环境，连Aura时不要用它。
另一个容易忽略的点是密码。Aura在创建实例时只会显示一次初始密码，如果忘了就得去控制台重置。重置后第一次连接务必成功登录，否则某些计划类型的实例可能会暂停，这一点在排查连接失败时要格外留意。
二、创建驱动实例并执行第一个查询
驱动的正确用法是整个应用生命周期只创建一个驱动实例，而不是每次查询都新建一个。驱动实例内部维护着连接池，频繁创建不仅浪费资源，还会拖慢响应速度。下面是一个完整的可运行示例，展示如何连接Aura并执行一条Cypher查询。
const neo4j = require('neo4j-driver');
// Aura控制台中复制的连接地址和凭证
const URI = 'neo4j+s://xxxxxxxx.databases.neo4j.io';
const USER = 'neo4j';
const PASSWORD = '你的Aura密码';
// 创建驱动实例，全局只需一个
const driver = neo4j.driver(
URI,
neo4j.auth.basic(USER, PASSWORD)
);
async function runQuery() {
// 会话用完必须关闭，推荐使用finally保证释放
const session = driver.session({ defaultAccessMode: neo4j.session.READ });
try {
const result = await session.run('MATCH (n) RETURN count(n) AS total');
const record = result.records[0];
console.log('节点总数:', record.get('total').toNumber());
} catch (err) {
console.error('查询失败:', err.message);
} finally {
await session.close();
}
}
runQuery().then(() => driver.close());这段代码里有三个关键点。第一，neo4j.auth.basic封装了基础认证，Aura的默认用户名就是neo4j，除非你在Aura控制台里另外创建了用户。第二，查询返回的数值类型不是JS原生的number，而是Neo4j的Integer对象，必须调用toNumber()转换，否则输出会变成奇怪的对象结构。第三，finally块里关闭session非常重要，忘记关闭会导致连接池被占满，后续查询排队等待甚至超时。
凭证管理方面，实际项目中不要把密码硬编码在代码里。推荐使用环境变量保存NEO4J_URI、NEO4J_USERNAME和NEO4J_PASSWORD，通过process.env读取，配合dotenv包在本地开发时加载.env文件，这样代码进入版本库也不会泄露密码。
三、连接池调优与会话管理实践
驱动默认的连接池配置对大多数场景够用，但高并发场景下需要调整。maxConnectionPoolSize控制池中最大连接数，默认100；connectionAcquisitionTimeout控制从池中获取连接的最长等待时间，默认60秒。如果并发请求量大，可以适当调大池子并缩短等待时间，让超载请求快速失败而不是排队堆积。
const driver = neo4j.driver(
URI,
neo4j.auth.basic(USER, PASSWORD),
{
maxConnectionPoolSize: 200, // 最大连接数
connectionAcquisitionTimeout: 5000, // 获取连接最多等5秒
maxConnectionLifetime: 3600 * 1000 // 连接最长存活1小时
}
);会话的读写模式也值得注意。session.READ会让驱动把查询路由到只读实例（在集群场景下），而session.WRITE保证写入走主实例。对于Aura单实例来说影响不大，但养成指定访问模式的习惯，将来迁移到集群版不需要改业务代码。
事务方面，简单的session.run隐式事务适合单条查询，而涉及多条写入时应该用显式事务函数session.executeWrite，它自带重试逻辑，遇到网络抖动或瞬时锁冲突会自动重试，比手写事务可靠得多。
四、常见连接报错排查
连接Aura时最典型的报错有三类。第一类是Server certificate authentication failed，通常是URI协议写错或者系统时间偏差太大导致证书校验失败，先检查URI是不是neo4j+s开头，再校准服务器时间。第二类是Authentication failed，多半是密码不对，去Aura控制台重置即可。第三类是连接超时，检查防火墙是否放行了7687端口的出站流量，云函数或容器环境尤其要确认出口网络没有限制。
还有一点提醒：Aura的免费实例在长时间无人访问后会自动暂停，首次访问需要等几十秒唤醒。如果你的应用部署后在第一次查询时偶发超时，很可能就是实例在冷启动，可以在应用初始化阶段发一条轻量查询来预热，或者升级到不会自动暂停的付费计划。排查时打开驱动的调试日志会有帮助，配置logging: neo4j.logging.console('debug')就能看到完整的连接握手过程。
Neo4j AuraNode.js连接Neo4jneo4j-driver修改时间：2026-09-09 07:48:52