Sanity groq 包完全指南:GROQ 标签模板字面量、自动类型推断与版本演进解读

原创2026-09-17 14:11:151,983 阅读
文章标签:CMS后端前端

Sanity groq 包完全指南:GROQ 标签模板字面量、自动类型推断与版本演进解读

groq 是 Sanity 官方 monorepo 中体积最小但使用面极广的基础包,它以 ES2015 标签模板字面量(tagged template literal)的形式承载 GROQ 查询的书写、语法高亮与未来校验能力。本文将基于仓库中 packages/groq 的实际源码、类型声明、双运行时测试与 CHANGELOG 的发布记录,完整讲解 groq 包的安装方式、groq 标签与 defineQuery 两个 API 的实现原理、ESM/CJS 双入口打包策略,以及 Node 版本支持策略的演进脉络,帮助你写出可被编辑器识别、可被 @sanity/codegen 推断类型、且能稳定运行在 Node 22+ 环境下的 GROQ 查询代码。

认识 groq 包:GROQ 查询的"标签模板字面量"

GROQ(Graph-Relational Object Queries)是 Sanity 内容平台面向结构化内容设计的查询语言。groq 包在其中的角色非常纯粹:导出一个函数,将一段 ES2015 模板字符串标记为 GROQ 查询。包自身的描述就是一句 "Tagged template literal for Sanity.io GROQ-queries"(见 packages/groq/package.json)。

它的核心价值体现在三方面:

  • 编辑器集成:经过标签标记的字符串,能让 vscode-sanity)。
  • 零运行时开销:调用结果与输入字符串完全一致,是一个纯粹的 pass-through(透传)实现,不解析、不校验、不转换。
  • 未来扩展点:如 README 所述,将来它可能被用于解析与校验查询、剥离无意义的空白字符等,因此在源码层面它是唯一适合注入这些能力的收口点。

安装与运行环境要求

在任意 Sanity 项目中安装只需一条命令:

npm install --save groq

安装后的使用方式(ESM):

import groq from 'groq'

const query = groq`*[_type == 'products'][0...10]`

当前仓库中 groq 的版本为 6.14.1(见 packages/groq/package.json),其对运行环境有两个值得注意的约束:

  • Node 版本:engines.node 声明为 >=22.12,即最低要求 Node.js 22.12.0。
  • 模块类型:"type": "module",默认走 ESM;但同时通过 main / module / exports 提供了 CJS 与 ESM 的双入口兼容(下文第四节详述)。
  • "sideEffects": false:向打包工具(如 webpack、Rollup、Vite)声明该模块没有副作用,支持 tree-shaking,被摇树剔除也不会破坏任何全局行为。

核心 API 与实现原理

groq 包对外暴露两个 API:默认导出的 groq 标签函数,以及命名导出的 defineQuery。两者都是 no-op(空操作),但面向的场景不同。

groq 模板标签:逐段拼接的透传实现

默认导出 groq 的实现位于 packages/groq/groq.js:

export default function groq(strings, ...keys) {
  const lastIndex = strings.length - 1
  return (
    strings.slice(0, lastIndex).reduce((acc, str, i) => acc + str + keys[i], '') +
    strings[lastIndex]
  )
}

JavaScript 标签模板函数的第一个参数 strings 是模板字符串被插值分隔后的静态片段数组,...keys 是所有插值表达式的求值结果。上面的实现等价于把两者按原顺序重新拼接回去,最终返回的字符串与输入的模板字面量逐字符一致。

这一点被 packages/groq/test/groq.test.mjs 与 packages/groq/test/groq.test.cjs 的断言完整覆盖,包括空模板、纯插值、字符串/数字/正则等多种插值类型混合的情况:

assert.equal(groq`foo${'bar'}`, `foo${'bar'}`)
assert.equal(groq``, ``)
assert.equal(groq`${'foo'}bar${347}${/qux/}`, `${'foo'}bar${347}${/qux/}`)
assert.equal(groq`${'foo'}${347}qux`, `${'foo'}${347}qux`)

也就是说,groq\...`` 与普通模板字符串在运行时行为上没有任何差异,它存在的意义是"语义标记"而非"执行逻辑"。

defineQuery:为自动类型推断而生

defineQuery 是一个普通函数而非标签函数,其实现仅一行(见 packages/groq/groq.js):

export function defineQuery(query) {
  return query
}

它的类型签名(见 packages/groq/groq.d.ts)使用了 const 类型参数,将字符串字面量类型完整保留下来:

export declare function defineQuery<const Q extends string>(query: Q): Q

配合 @sanity/codegen 使用,即可在无需额外标注类型的情况下,让查询返回结果自动获得精确的 TypeScript 类型推断:

import {defineQuery} from 'groq'

const query = defineQuery(`*[_type == 'products'][0...10]`)

关于为什么不能直接让 groq 标签函数具备同样的类型推断能力,源码注释给出了明确原因:TypeScript 目前尚无法从标签模板(tagged template)中推断类型(见 packages/groq/groq.js 中引用的 microsoft/TypeScript#33304 问题)。未来待 TypeScript 支持后,defineQuery 有望与 groq 合并,但目前两者并存、各司其职:groq 负责编辑器高亮,defineQuery 负责编译期类型安全。defineQuery 的行为同样有测试兜底(见 packages/groq/test/define.test.mjs),验证了它对字符串的完全透传。

ESM 与 CJS 双入口:一份代码,两种运行时

groq 虽然 "type": "module",但必须同时服务 ESM 与 CommonJS 两种消费方,因此 package.json 通过 exports 字段精确映射了四条入口(见 packages/groq/package.json):

"exports": {
  ".": {
    "require": {
      "types": "./groq.d.cts",
      "default": "./groq.cjs"
    },
    "types": "./groq.d.ts",
    "default": "./groq.js"
  },
  "./package.json": "./package.json"
}
  • ESM 消费者:import groq from 'groq' 命中 default 分支,加载 groq.js,类型声明取 groq.d.ts。
  • CJS 消费者:require('groq') 命中 require 分支,加载 groq.cjs,类型声明取 groq.d.cts。

CJS 版本在导出方式上与 ESM 版本有个微妙差异(见 packages/groq/groq.cjs):

// `require('groq')` returns the tag function itself
module.exports = groq
module.exports.defineQuery = defineQuery

即 require('groq') 直接返回 groq 标签函数本身,而 defineQuery 以属性的形式挂载其上。对应的类型声明 groq.d.cts 使用 export = groq 加 declare namespace groq 的结构,精确复刻了这一运行时形状,保证 CJS 侧也能获得完整类型提示。这一双入口结构正是"版本同步发布"策略在产物层面的体现——两份运行时实现共享同一份语义与同一套测试。

从 CHANGELOG 看 groq 的版本演进脉络

packages/groq/CHANGELOG.md 记录了这一包的完整发布历史。其中绝大多数条目标注为 "Note: Version bump only for package groq",这说明 groq 是 Sanity 多包 monorepo(pnpm workspace)的一部分,会跟随主版本节奏同步升版,其自身 API 在很长一段时间内保持稳定。真正值得关注的实质变更集中在以下几类:

Node 版本支持策略的逐步收紧

这是 groq 历史变更中唯一的 Breaking Change 主线,体现了 Sanity 对运行时基线的前瞻性管理:

版本 变更内容 含义
4.0.0(2025-07-14) ⚠️ remove node 18, make base 20 移除 Node 18 支持,基线提升到 Node 20
4.4.0(2025-08-13) update engines to require node >=22.12.0 进一步将最低要求提升至 Node 22.12.0
4.4.1(2025-08-14) allow v20 in node engines 短暂放宽,允许 Node 20
6.0.0(2026-06-11) ⚠️ drop support for node 20 移除 Node 20,最终收敛到当前 engines: node >=22.12 的约束

对比当前 package.json 中的 "engines": {"node": ">=22.12"} 可以看到,这一策略已经稳定执行。对使用者的实际影响:如果项目运行在 Node 20 及以下版本,应锁定 groq 的 4.x 分支;升级到 6.x 前需要先将 Node 运行时提升到 22.12 以上。

CJS 类型导出的修复与回归

5.13.0(2026-03-03)的 Bug Fix 记录为 "resolve CJS type export issue by removing groq.d.cts"。但以当前仓库文件列表为准,packages/groq/groq.d.cts 依然存在并被 exports.require.types 引用。可以推断,该问题的修复在后续版本中演变为"重新提供独立的 .d.cts 声明文件"这一更完整的方案——这也与 exports 映射中 require/types 单独指向 .d.cts 的现状相互印证。

发布产物精简

3.94.0(2025-06-24)的变更 "stop publishing src folders to npm" 表明:从该版本起,npm 包不再发布源码文件夹,仅保留 groq.cjs、groq.d.cts、groq.d.ts、groq.js 四个产物文件(与 package.json 的 files 字段完全对应),包体积与安装耗时因此得到优化。

其他同步性变更

5.15.0(2026-03-12)记录为 "upgrade to new @sanity/cli",属于工具链层面的跟随升级,不影响 groq 的运行时 API。整体来看,groq 的 API 面自发布以来保持高度稳定,变化集中在运行环境约束与打包产物策略上。

测试策略:双运行时下的行为一致性

groq 的测试脚本为 node --test(见 packages/groq/package.json),即直接使用 Node 内置测试运行器,无需额外测试框架。仓库中共有 4 个测试文件,按"运行时 × API"组合划分:

测试文件 覆盖对象
test/groq.test.mjs ESM 下的 groq 标签函数
test/groq.test.cjs CJS 下的 groq 标签函数
test/define.test.mjs ESM 下的 defineQuery
test/define.test.cjs CJS 下的 defineQuery

测试断言涵盖三个方面:导出对象类型正确(typeof groq === 'function')、可通过 groq/package.json 子路径读取版本号、以及各种插值组合下输入输出逐字相等。这套测试保证了"同一语义在 ESM 与 CJS 两种运行时下行为完全一致",也间接验证了 exports 映射的正确性。

在 Sanity 项目中的典型使用方式

groq 包通常与 Sanity 的客户端配合使用,典型模式如下:

import groq from 'groq'
import {createClient} from '@sanity/client'

const client = createClient({projectId: 'your-project-id', dataset: 'production', apiVersion: '2024-01-01'})

const query = groq`*[_type == 'product']{title, price, "slug": slug.current}`
const products = await client.fetch(query)

如果项目已经接入 @sanity/codegen 做类型生成,则优先使用 defineQuery 以获得查询结果的自动类型推断。从仓库的 dev 目录可以看到,Sanity 本身维护了大量基于此工作流构建的 Studio 示例工程(如 test-studio、radar 等),其查询代码均围绕这套标签模板范式组织。

小结

groq 包用极简的实现承担了 GROQ 查询开发体验的基础设施职责:groq 标签为编辑器提供语义标记,defineQuery 为 @sanity/codegen 提供类型推断入口,ESM/CJS 双入口保证任意模块体系下的可用性,而 CHANGELOG 则清晰记录了 Node 版本基线从 18 → 20 → 22.12 的收紧过程。对使用者而言,记住两条实操结论即可:Node 22.12+ 环境可直接使用最新版;需要类型推断时用 defineQuery,否则用 groq 标签即可。

登录后查看全文
sanity