Node.js环境下Google Spreadsheet API v4条件查询指定行失效

你当前的写法在3.1.15版本的google-spreadsheet库下没达到筛选效果，本质是三个规则没对齐：

• 这个版本的getRows的query参数是直接透传给Google Sheets服务端的Visualization Query引擎，引擎有严格的语法要求：字符串类型的匹配值必须用单引号包裹。你写的Clan = clan-12没给clan-12加单引号，服务端直接解析失败，相当于把筛选参数丢了，返回全表的行，自然看不到筛选效果。
• query里写的字段名，必须和工作表的表头内容（默认取第一行的单元格值）大小写、甚至不可见的空格完全一致——要是你表头实际是小写clan，或者单元格末尾带了个复制粘贴进来的看不见的空格，你写Clan首字母大写，永远匹配不到。
• 哪怕你query写对了，这个方法也不会自动只返回第一条匹配的行，返回的是所有符合条件的行列表，需要自己取第一条才能满足“拿单条记录”的需求。

按照服务端要求调整query格式后，核心改动是给字符串匹配值补单引号，同时直接取第一条匹配结果即可：

(async () => {
    await doc.useServiceAccountAuth(creds);
    await doc.loadInfo();
    const sheet = doc.sheetsByIndex[1];
    // 修正点：字符串匹配值用单引号包裹，等号前后空格不影响引擎解析
    const rows = await sheet.getRows({
        query: "Clan = 'clan-12'"
    });
    // 直接取第一条匹配结果，无需遍历全量数组
    const matchedRow = rows[0];
    if (matchedRow) {
        printStudent(matchedRow);
    }
})()

function printStudent(data){
    console.log(data.Clan);
    console.log(data.SheetId);
    console.log(data.Enabled);
}

• 如果你的实际表头不在工作表第一行（比如第一行是大标题、第二行才是字段名），需要在getRows参数里显式指定headerRow（从0开始的行索引），比如表头在第2行就写headerRow: 1，否则字段映射错乱，即使query写对也无法匹配。
• 如果调整语法后query仍然不生效，可以先打印返回的rows数组，逐字对比row对象的属性名和你query里写的字段名——很多时候表头单元格会有复制粘贴带进来的不可见空格，导致属性名和预期不一致。
• 对于大行数的工作表，可以在getRows参数里显式缩小range范围，减少服务端返回的数据量，避免因为全表扫描带来的延迟。
• 如果不需要调用行对象的save/delete等实例方法，可以直接取row._rawData作为纯数据使用，减少不必要的内存开销。

内容的提问来源于stack exchange，提问作者COdeingNinja