在 Node.js 服务里连接 Neo4j 时，可能会遇到这样的报错：Connection acquisition timed out。它传达的信息并不是数据库进程宕机，而是驱动程序在向连接池申请连接时，等待了指定时间仍然没有拿到可用连接。理解这一点是解决问题的关键。很多团队第一反应是扩大连接池或增加超时时间，但如果连接泄漏或慢查询没有解决，这些配置只会把问题推迟。
连接获取超时的触发机制
Neo4j 官方提供的 neo4j-driver 默认维护一个连接池。应用调用 session.run() 时，驱动不会立刻创建 TCP 连接，而是从池中获取一个空闲连接。如果池中没有空闲连接，并且当前连接数已经达到 maxConnectionPoolSize，请求会进入等待队列。connectionAcquisitionTimeout 就是等待队列的最长等待时间，默认值通常是 60 秒。超过这个时间，驱动就会抛出获取连接超时错误。
这里要区分两个容易混淆的超时：connectionTimeout 是建立单个 TCP 连接的超时，而 connectionAcquisitionTimeout 是从连接池获取连接的超时。前者衡量网络连接建立速度，后者衡量连接池的供给能力。如果连接池大小合理但数据库响应慢，所有连接都被慢查询占满，新请求依然会等待超时。
连接池的工作方式可以简单理解为：有可用连接就直接分配；没有但未达到上限就新建连接；达到上限则排队。因此触发获取超时通常意味着池子已经被占满，并且持续了整整一个超时周期。这种情况下，单纯调大超时时间只会让请求阻塞更久，并不能从根本上提升吞吐。
常见原因与排查思路
第一大原因是连接泄漏。Node.js 中如果忘记调用 session.close()，或者事务没有提交或回滚，连接就不会归还连接池。随着请求增多，池中连接逐渐耗尽，最终所有请求都在等待获取连接。排查时可以记录每次创建会话的数量和关闭数量，也可以接入驱动的日志，观察连接池状态。
第二大原因是慢查询。即使没有连接泄漏，如果大量 Cypher 查询执行时间超过几秒甚至几十秒，连接被长时间占用，连接池同样会枯竭。此时需要查看 Neo4j 的查询日志，找到慢查询并进行索引优化、查询重构或增加硬件资源。数据库端可以用 EXPLAIN 和 PROFILE 分析执行计划。
第三大原因是连接池配置过小。默认的 maxConnectionPoolSize 是 100，但对于突发流量较大的服务来说，如果并发数超过这个值，排队就会成为常态。不过这并不意味着越大越好，Neo4j 服务端也有连接数限制，过大的池子会增加内存和线程开销。合理设置应基于压测数据，而不是盲目调大。
其他常见原因还包括 DNS 解析缓慢、TLS 握手耗时较长、网络抖动等。DNS 问题通常表现为首次建立连接很慢，但连接建立后查询正常；TLS 问题可以通过关闭加密连接做对比测试来确认。建议在测试环境逐项排除，避免同时修改多个变量。
代码示例：正确配置连接池
下面的示例展示了如何在 Node.js 中初始化 Neo4j 驱动，并合理设置连接池参数。注意 connectionAcquisitionTimeout 的单位是毫秒，建议不要设置得过大，一般 10 到 30 秒足够。连接池大小则根据并发量和数据库承载能力综合决定。
const neo4j = require('neo4j-driver');
const driver = neo4j.driver(
'neo4j://localhost:7687',
neo4j.auth.basic('neo4j', 'your-password'),
{
maxConnectionPoolSize: 80,
connectionAcquisitionTimeout: 15000,
connectionTimeout: 10000,
logging: {
level: 'info',
logger: (level, message) => console.log(`${level} ${message}`)
}
}
);
async function runQuery() {
const session = driver.session();
try {
const result = await session.run('MATCH (n) RETURN count(n) AS count');
const record = result.records[0];
console.log(record.get('count').toString());
} catch (error) {
console.error('Query failed:', error);
} finally {
await session.close();
}
}
finally 块中的 session.close() 非常关键，它能保证无论查询成功还是失败，会话都会归还连接池。如果省略，代码一旦抛错，连接就可能一直占用。对于事务操作，还应该使用 session.readTransaction() 或 session.writeTransaction()，这些方法会在事务结束后自动释放资源。
验证与监控连接池状态
调整配置后，需要验证问题是否真正解决。可以先用压力测试工具模拟并发请求，观察是否还会出现获取连接超时。测试时重点监控两个指标：连接池的活跃连接数和等待队列长度。通过驱动日志可以看到连接创建和释放的过程，也可以自行在代码里维护一个计数器。
在 Neo4j 服务端，可以通过 CALL dbms.listConnections() 查看当前连接来源和状态，结合客户端驱动日志判断连接是否被正常归还。如果发现连接数持续增长且很少下降，说明存在连接泄漏；如果连接数达到上限但查询耗时很高，说明需要优化查询。
更完整的做法是接入指标采集系统，例如将连接池状态定时输出到日志或监控平台。Node.js 驱动没有直接暴露连接池统计接口，但可以通过包装 driver.session() 方法记录会话创建数，并在 session.close() 时记录关闭数。当两者差值长期不为零，就需要检查代码中是否有遗漏关闭会话的分支。
总结
Connection acquisition timed out 本质上是连接池资源紧张的表现。解决步骤应当先从连接是否正确释放入手，再检查慢查询和池配置，最后考虑网络与 TLS 等环境因素。保持会话生命周期清晰、合理设置池大小和超时时间、监控连接池状态，能有效减少此类问题。对大多数 Node.js 服务来说，把 connectionAcquisitionTimeout 控制在 15 秒左右，并确保 session.close() 放在 finally 中是性价比最高的两项改进。