Storyblok GraphQL怎么用 内容查询接口教程

Storyblok GraphQL是Storyblok的内容查询接口，可以用GraphQL语法精准查询内容，适合做前后端分离的网站和应用。它是只读接口，适合读取空间里的内容并交给前端渲染；新增、修改或删除内容要使用相应的管理接口。下面从令牌、查询和前端请求三步开始，带你走通一次基础调用。

第一步：获取API令牌

先登录Storyblok后台，进入要读取内容的Space，找到设置中的Access Tokens区域。创建或查看适用于内容读取的API访问令牌，并确认令牌属于正确的Space。这里要用Content Delivery相关令牌，不要把Management API的个人令牌当成内容查询令牌；两者用途不同，拿错后请求通常会因认证失败而无法返回内容。

接着确认Space所在区域，因为GraphQL接口地址会随数据区域变化。常见欧洲区域地址是https://gapi.storyblok.com/v2/api，美国、加拿大、澳大利亚和中国区域则有各自的域名。按Space的实际区域选择地址，不要仅凭访问者所在国家判断。开发时可先把接口地址和令牌放进环境变量，避免散落在代码文件中。

如果需要读取尚未发布的草稿，在请求头中设置Version为draft；展示正式上线的内容时使用published。令牌与版本要配套检查：拿预览用途令牌却查询发布内容，或在预览环境漏掉版本设置，都可能导致结果和后台看到的不一致。先把令牌保存到本地安全配置，确认能正常请求后，再继续编写查询。

第二步：编写GraphQL查询

GraphQL会根据Storyblok中的组件类型生成查询字段。比如组件名为page时，常见字段是PageItems（列表）和PageItem（单条）；blog-article会转换为BlogArticleItems和BlogArticleItem。字段名与组件名有关，大小写也要吻合。打开GraphQL Playground并填入访问令牌，可以查看当前Space实际生成的字段和可选内容字段。

初次查询建议从列表开始，只取页面名称、全名、发布时间等确实需要展示的字段。查询结构可写作query { PageItems { items { name full_slug } total } }；其中PageItems对应列表，items里列出想取的属性，total可用于了解结果总数。字段必须存在于当前组件类型中，若返回字段错误，先在Playground检查Schema，而不是盲目增加字段。

运行查询后查看响应JSON，重点检查data下的结果列表以及errors信息。若data为空，先核对字段名称、Space区域和内容发布状态；若出现errors，按提示确认查询字段是否属于该组件。开发阶段只选择页面真正用到的字段，避免一次抓取过多内容；GraphQL虽能合并读取需求，复杂查询仍会增加请求成本。

使用过滤和排序参数

需要分页时，可在列表字段上使用接口支持的分页参数，例如per_page与page，并读取返回的total判断是否还有下一页。每页数量应按页面需求设置，不要默认一次拉取所有内容。具体参数和类型以当前Schema为准；在Playground中点开PageItems的参数说明，可确认哪些参数可用、参数类型是什么，再将它们加入查询。

过滤和排序同样先从Schema确认。不同内容类型与API版本支持的参数可能不同，不能把其他接口的URL查询参数直接照搬成GraphQL参数。找到可用的过滤条件后，先用一两个条件验证结果，再逐步增加组合条件；排序字段则选择确实存在且适合列表展示的字段，并检查升序、降序的写法是否符合参数定义。

• 列表太长：设置分页参数，并依据total逐页读取。
• 结果不对：检查过滤字段、内容状态和当前区域的Schema。
• 请求成本偏高：减少返回字段、缩小单页数量，避免不必要的嵌套连接。

第三步：在前端调用API

浏览器或服务端都可以用HTTP POST调用GraphQL接口，请求体放入query字符串，请求头携带Token、Version和Content-Type: application/json。将查询发送到所选区域的/v2/api地址，再把响应解析为JSON。开发时可以先打印data与errors，确认数据结构无误后，再映射到页面组件；正式环境则应处理网络失败和非成功状态码。

前端展示时，把返回的items映射成卡片或列表，并对缺失字段设置合适的默认显示。若内容包含富文本或嵌套组件，先按实际响应结构解析，避免把对象直接当普通字符串渲染。公开访问令牌仍应按项目的安全方案管理；涉及预览或敏感流程时，优先由服务端代理请求，不要把不该公开的凭据放进浏览器代码。

上线前分别测试草稿预览和正式发布版本，并模拟空列表、翻页、请求失败等情况。GraphQL接口有请求成本限制，出现429时应减少频率、稍后重试，并避免短时间重复发送相同复杂查询。若团队还在比较建站和原型工具，国内替代方案可了解墨刀AI；也可访问modao.cgref.cn查看相关介绍。润灭建议先用Playground验证查询，再接入项目。