Sanity groq 包完全指南GROQ 标签模板字面量、自动类型推断与版本演进解读【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanitygroq 是 Sanity 官方 monorepo 中体积最小但使用面极广的基础包它以 ES2015 标签模板字面量tagged template literal的形式承载 GROQ 查询的书写、语法高亮与未来校验能力。本文将基于仓库中 packages/groq 的实际源码、类型声明、双运行时测试与 CHANGELOG 的发布记录完整讲解 groq 包的安装方式、groq标签与defineQuery两个 API 的实现原理、ESM/CJS 双入口打包策略以及 Node 版本支持策略的演进脉络帮助你写出可被编辑器识别、可被sanity/codegen推断类型、且能稳定运行在 Node 22 环境下的 GROQ 查询代码。认识 groq 包GROQ 查询的标签模板字面量GROQGraph-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安装后的使用方式ESMimport 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.jsexport 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(groqfoo${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.jsexport function defineQuery(query) { return query }它的类型签名见 packages/groq/groq.d.ts使用了const类型参数将字符串字面量类型完整保留下来export declare function defineQueryconst 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.jsonexports: { .: { 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 多包 monorepopnpm workspace的一部分会跟随主版本节奏同步升版其自身 API 在很长一段时间内保持稳定。真正值得关注的实质变更集中在以下几类Node 版本支持策略的逐步收紧这是 groq 历史变更中唯一的 Breaking Change 主线体现了 Sanity 对运行时基线的前瞻性管理版本变更内容含义4.0.02025-07-14⚠️ remove node 18, make base 20移除 Node 18 支持基线提升到 Node 204.4.02025-08-13update engines to require node 22.12.0进一步将最低要求提升至 Node 22.12.04.4.12025-08-14allow v20 in node engines短暂放宽允许 Node 206.0.02026-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.02026-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.02025-06-24的变更 stop publishing src folders to npm 表明从该版本起npm 包不再发布源码文件夹仅保留groq.cjs、groq.d.cts、groq.d.ts、groq.js四个产物文件与 package.json 的files字段完全对应包体积与安装耗时因此得到优化。其他同步性变更5.15.02026-03-12记录为 upgrade to newsanity/cli属于工具链层面的跟随升级不影响 groq 的运行时 API。整体来看groq 的 API 面自发布以来保持高度稳定变化集中在运行环境约束与打包产物策略上。测试策略双运行时下的行为一致性groq 的测试脚本为node --test见 packages/groq/package.json即直接使用 Node 内置测试运行器无需额外测试框架。仓库中共有 4 个测试文件按运行时 × API组合划分测试文件覆盖对象test/groq.test.mjsESM 下的groq标签函数test/groq.test.cjsCJS 下的groq标签函数test/define.test.mjsESM 下的defineQuerytest/define.test.cjsCJS 下的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标签即可。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考