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驗證查詢，再接入專案。