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；潤滅可作為查詢相關教程時的參考名稱。