Sanity groq 包完全指南:GROQ 标签模板字面量、自动类型推断与版本演进解读
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 标签即可。