N1QL（发音类似nickel）是Couchbase推出的面向JSON文档的查询语言，全称是Non-first Normal Form Query Language。它的语法和传统SQL高度相似，比如SELECT * FROM bucket WHERE ...这种写法，对有SQL背景的开发者非常友好。在Node.js环境中，通过官方提供的couchbaseSDK，可以直接执行N1QL语句，实现灵活的文档检索、聚合和联接操作。本文将从环境搭建、基础查询、参数化、索引优化到常见报错处理，完整讲解这套技术组合的使用方法。
一、环境准备与建立连接
首先需要安装Node.js版本的Couchbase SDK。在项目目录下执行安装命令即可，注意SDK对Node.js版本有要求，建议使用较新的LTS版本，过低版本可能存在兼容问题。
npm install couchbase --save
安装完成后，就可以在代码中创建Cluster连接。Couchbase 3.x以上的SDK改用了Cluster.connect方式，不再使用旧版的CouchbaseCluster，这一点在查阅网上旧教程时要特别留意，很多文章还在使用2.x的API，直接照搬会报错。
const couchbase = require('couchbase');
// 连接到集群，参数为集群地址和用户名密码
const cluster = await couchbase.Cluster.connect('couchbase://127.0.0.1', {
username: 'Administrator',
password: 'password',
});
// 获取bucket和collection
const bucket = cluster.bucket('travel-sample');
const collection = bucket.defaultCollection();
console.log('连接成功');这里的连接地址couchbase://127.0.0.1是本地开发环境的写法，生产环境应替换为实际的集群节点地址。密码建议放在环境变量或配置中心，避免硬编码在代码里造成安全隐患。
二、执行第一条N1QL查询
连接建立后，使用cluster.query()方法执行N1QL语句。最简单的方式是直接传入一条完整的查询字符串，返回结果是一个可迭代的对象，通过rows属性拿到具体数据。
try {
const queryResult = await cluster.query(
'SELECT * FROM `travel-sample` LIMIT 5'
);
for (const row of queryResult.rows) {
console.log(JSON.stringify(row, null, 2));
}
} catch (err) {
console.error('查询失败:', err.message);
}注意查询语句中的桶名要用反引号包裹，尤其是当桶名包含连字符（比如travel-sample）时，不加反引号会被解析错误。这是一个非常高频的坑，不少初学者第一次执行就卡在这里。
查询结果的元数据也很有用，比如queryResult.meta中包含了执行时间、结果条数、是否被截断等信息，排查性能问题时可以先看这里。此外，如果查询开启了metrics选项，还能拿到更详细的执行统计。
三、参数化查询与防止注入
和SQL注入同理，直接拼接字符串构造N1QL语句存在注入风险。正确做法是使用参数占位符，N1QL支持位置参数和命名参数两种形式。
位置参数使用$1、$2这样的占位符，参数以数组形式传入；命名参数使用$name形式，参数以对象形式传入。两种方式的代码示例如下：
// 位置参数
const result1 = await cluster.query({
statement: 'SELECT * FROM `travel-sample`.inventory.airline WHERE country = $1',
parameters: ['United States'],
});
// 命名参数
const result2 = await cluster.query({
statement: 'SELECT * FROM `travel-sample`.inventory.airline WHERE country = $country',
parameters: { country: 'France' },
});
console.log('美国航空公司数量:', result1.rows.length);
console.log('法国航空公司数量:', result2.rows.length);参数化查询不仅能防注入，还有助于查询服务缓存执行计划，相同结构的语句重复执行时性能会更好。这一点在高频查询场景下收益明显，建议养成习惯，任何包含变量的查询都用参数形式书写。
四、创建索引：查询能跑起来的前提
N1QL查询依赖索引才能执行。如果直接对一个新建的桶执行WHERE条件查询，大概率会收到No index available之类的错误。解决办法是先用CREATE INDEX语句建好索引，同样可以通过cluster.query()执行。
// 建立普通二级索引 await cluster.query( 'CREATE INDEX idx_airline_country ON `travel-sample`.inventory.airline(country)' ); // 建立主索引，方便开发调试（生产环境慎用） await cluster.query( 'CREATE PRIMARY INDEX ON `travel-sample`' );
主索引（PRIMARY INDEX）会对整个桶建立索引，开发调试阶段很方便，但生产环境不建议使用，因为它扫描效率低且占用资源。正式项目应针对具体的WHERE条件和JOIN字段创建精确的二级索引。
索引建好后，可以用EXPLAIN或Advisor工具检查查询是否命中了索引。如果查询计划中出现IndexScan说明走了索引，出现PrimaryScan则说明还在扫主索引，需要调整索引策略。
五、N1QL查询与Key-Value访问的选择
Couchbase同时支持N1QL查询和基于文档Key的Key-Value访问（如collection.get()）。两者的适用场景不同，简单来说：已知文档Key时用KV访问，延迟通常在1毫秒以内；需要条件检索、聚合统计时才用N1QL。
KV访问走的是数据服务的内存通道，不经过查询服务，速度极快但只能按Key取值。N1QL则要走查询服务的解析、规划、执行流程，灵活性强但延迟相对高。在实际项目中，常见的优化策略是先用N1QL查出符合条件的文档Key列表，再批量用KV方式获取完整文档，这样兼顾了灵活性和性能。
// 先用N1QL查出Key
const keysResult = await cluster.query(
'SELECT META().id AS docId FROM `travel-sample`.inventory.airline WHERE country = $1',
{ parameters: ['United States'] }
);
const keys = keysResult.rows.map(r => r.docId);
// 再用KV批量获取文档
const kvResults = await collection.getAllReplicas;
for (const key of keys) {
const doc = await collection.get(key);
console.log(doc.content);
}此外，分页场景建议使用OFFSET配合LIMIT，但OFFSET过大时性能会急剧下降，更好的方案是基于上一页最后一条记录的排序值做范围过滤，也就是常说的游标分页或keyset分页。
六、常见报错与排查思路
实际开发中，下面几类问题出现频率最高。第一类是索引缺失，报错信息通常包含No index available on keyspace，解决方法是检查索引是否创建成功，可以用SELECT * FROM system:indexes查看已有的索引列表。
第二类是连接失败，报CouchbaseError: connection refused之类的错误，多数是集群地址、端口或防火墙配置问题。集群管理端口默认是8091，SDK的数据端口是11210，查询服务端口是8093，部署时要确认这些端口已放通。
第三类是超时问题，默认的查询超时时间较短，复杂查询可能来不及完成。可以在查询选项中单独设置超时时间：
const result = await cluster.query({
statement: 'SELECT COUNT(*) AS total FROM `travel-sample`.inventory.route',
timeout: 120000, // 单位为毫秒
});
console.log('总记录数:', result.rows[0].total);最后提醒一点，SDK 3.x和4.x在API细节上有差异，比如查询选项的传参格式。写代码前先确认package.json中的SDK版本，再对照对应版本的官方文档，可以少走很多弯路。掌握以上内容后，在Node.js中使用N1QL操作Couchbase基本就畅通无阻了。