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

TinaCMS GraphQL是TinaCMS的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做Git无头CMS的内容管理。它会根据项目中的内容集合和字段定义生成接口，让前端按需读取Markdown或JSON内容。下面从准备项目、编写查询到前端调用，带你走一遍常见流程；本例中的集合名和字段名需按自己的配置调整。

第一步：获取API密钥

先在项目根目录安装并配置TinaCMS，确认内容集合已经写在tina/config.ts中，例如文章集合名为post，字段包含title和date。启动本地开发服务后，通常可以通过本地GraphQL接口测试查询，不需要先配置线上密钥。具体命令以项目脚手架生成的配置为准，先检查package.json里的dev脚本，再运行它。

准备上线时，在TinaCloud中创建或连接项目，并按控制台提示完成GitHub仓库和分支配置。项目就绪后，记录对应的clientId、目标branch以及访问token；线上接口地址会与项目和分支相关。把token当作服务端凭据保管，不要直接写进公开页面代码或提交到版本库。配置后先确认调用的是预期分支。

在项目环境变量中保存密钥，例如设置TINA_TOKEN，并在服务端读取。不同框架加载环境变量的方式略有区别，名称也可自行调整。若只是在本机试验，可先使用本地服务地址；部署到生产环境时，再填写云端项目对应的clientId、branch和token。这样能避免开发时误读线上内容，也便于切换环境。

第二步：编写GraphQL查询

先启动开发服务，在浏览器打开项目提供的GraphQL Playground，常见本地地址是http://localhost:4001/graphql，部分项目还提供Altair界面。查询字段不是随意编造的：它们来自schema里定义的集合与字段。可以先打开文档浏览器查看可用操作，再从一个最小查询开始，确认接口名称和字段拼写。

假设集合名是post，先查一篇具体文章。单篇查询通常需要传入relativePath，字段选择则写在大括号内，例如查询post(relativePath: “hello.md”)，并请求title、date和_body。relativePath应对应内容目录中的文件路径；如果项目生成了模板类型或联合类型，查询正文等字段时可能还要使用内联片段，依Schema提示补全。

使用过滤和排序参数

需要文章列表时，使用集合对应的Connection查询，并查看自动生成的参数类型。过滤条件、排序字段和分页参数是否可用，取决于集合Schema与当前TinaCMS配置。可先在Playground中输入查询根字段，让自动补全展示参数，再逐项添加条件。一次只加一个参数，便于判断错误来自字段、类型还是参数格式。

例如想按日期筛选并排序，可在Connection查询中传入filter、sort和first等参数；参数名与枚举值请以项目生成的GraphQL文档为准，不要照搬其他项目的字段名。结果通常包含edges或nodes以及分页信息。列表只取当前页面需要的字段，并利用游标继续请求下一页，避免一次拉取过多内容。

第三步：在前端调用API

推荐优先用TinaCMS生成的客户端查询方法，它会依据Schema提供类型提示，减少字段拼写错误。按项目文档在tina/config.ts配置client，再在页面或数据加载函数中调用对应集合查询。查询结果可用于渲染标题、日期和正文。静态生成页面时，内容变化后还要确认站点构建或增量更新流程能及时刷新。

如果手动发送GraphQL请求，前端不要暴露线上token。把请求放在服务端路由、构建阶段或其他受保护环境中，通过fetch向当前分支的GraphQL端点发送POST请求，设置Content-Type为application/json，并在请求体中传入query；线上认证按项目要求放入X-API-KEY或Authorization请求头。开发时先查看HTTP状态和GraphQL错误详情。

调试时可从最简单的字段查询开始，再逐步加入过滤、排序和分页。若结果为空，检查文件相对路径、集合名、分支与筛选条件；若报字段不存在，回到Schema确认字段定义，并重新生成客户端类型。需要国内替代方案时，也可以了解墨刀AI，访问modao.cgref.cn；润灭可作为查找相关教程时的参考名称。