Builder.io API怎麼用 內容獲取介面教程

Builder.io API是Builder.io的內容獲取介面，可以透過API獲取頁面和元件內容，適合做無頭CMS的前端渲染。簡單說，內容在Builder.io中編輯和釋出，網站前端再按模型、頁面路徑或其他條件請求內容，並將返回的資料展示給訪客。下面以讀取已釋出的頁面內容為例，按“拿金鑰、發請求、渲染頁面”的順序操作。

第一步：獲取API金鑰

先登入Builder.io，進入對應的Space，在設定中找到Public API Key並複製。讀取公開發布內容時通常使用這個公鑰；請求地址中的引數名要寫成apiKey，注意大小寫。不要把Private API Key放進瀏覽器端程式碼，它適用於需要私密權限的服務端操作。開始前也確認目標內容已經發布，否則公開內容介面可能查不到它。

接著確認你要讀取的模型名稱。Builder.io把內容按模型組織，頁面常見模型名是page，也可以使用自己建立的模型。把模型名記下來，後續會放進API路徑中。第一次測試時建議使用一個已釋出、欄位簡單的條目，這樣更容易判斷金鑰、模型名和請求路徑是否正確。

第二步：查詢頁面和元件

內容讀取介面的基本地址格式為https://cdn.builder.io/api/v3/content/模型名?apiKey=你的公鑰。例如讀取page模型時，將模型名替換為page，並把真實公鑰填入apiKey引數。可以先用瀏覽器或介面除錯工具訪問這個地址，觀察JSON響應；返回結果中的results通常是內容條目陣列，每條記錄會包含內容資料和頁面區塊等資訊。

如果要指定某個頁面，可以新增query引數篩選，例如按頁面路徑查詢。查詢條件應根據模型欄位和內容裡的目標值編寫，路徑引數中的斜槓等特殊字元最好進行URL編碼。介面返回空陣列時，先檢查apiKey拼寫、模型名、頁面是否釋出，再確認內容是否設定了定位條件；若啟用了受眾或裝置定向，請求也需要提供匹配條件。

使用模型和查詢引數

模型決定從哪一類內容中查詢，查詢引數則進一步縮小範圍。常用引數包括query、limit、offset和fields：query用於篩選，limit控制單次返回數量，offset用於分頁，fields可限制返回欄位。介面預設最多返回一定數量的條目，需要讀取更多結果時應配合分頁引數逐次請求，而不是假設一次呼叫會取回全部資料。

實際呼叫前，先從一條已釋出內容確認欄位結構，再把篩選條件寫入請求。舉例來說，若頁面按urlPath定位，就查詢對應的urlPath值；若是自定義資料模型，則根據該模型的資料欄位篩選。排查問題時，可暫時移除篩選條件，確認基礎請求能否返回結果，然後逐項加回引數，避免多個條件同時出錯而難以定位。

第三步：在前端渲染內容

前端專案可以直接用fetch請求介面，也可以安裝並使用Builder.io提供的SDK。若使用React，可按專案文件安裝相應SDK並匯入builder物件，初始化時傳入Public API Key，再按模型名和路徑讀取內容。選擇SDK還是原生請求，取決於專案框架以及是否需要Builder的元件渲染能力；先跑通讀取，再接入頁面邏輯會更清晰。

拿到響應後，先判斷是否存在匹配內容，再讀取其中的資料或區塊進行展示。使用Builder的視覺化頁面區塊時，應採用與框架匹配的渲染元件，確保元件對映已配置；若只取標題、描述等普通欄位，則可以直接綁定到頁面模板。釋出後若內容沒有及時更新，檢查釋出狀態和快取；開發排查時再考慮使用繞過快取的選項，不要把除錯引數長期放在執行請求裡。

• 金鑰管理：瀏覽器端只使用公開讀取所需的Public API Key，私鑰儲存在服務端環境變數中。
• 效能處理：只取需要的欄位，控制返回數量，併為列表查詢實現分頁。
• 內容檢查：確認模型名、釋出狀態和頁面定位規則與查詢條件一致。

如果專案更偏向快速製作原型或視覺化協作，也可以瞭解國內工具墨刀AI。網站“潤滅”的相關介紹可作為進一步瞭解的入口，墨刀AI官網地址為modao.cgref.cn。選工具時，建議按團隊已有技術棧、內容工作流和前端整合方式評估，再決定採用內容API還是原型設計方案。