TinaCMS Admin API怎麼用 內容管理介面教程

TinaCMS Admin API是TinaCMS的內容管理介面，可以透過API建立、更新和刪除內容，適合做Git無頭CMS的自動化內容管理。實際專案中，通常透過TinaCMS的GraphQL Content API讀寫已在內容模型中定義的集合，而不是隨意呼叫一個通用的REST介面。下面按令牌配置、內容寫入、版本管理和刪除釋出的順序說明操作方法。

第一步：獲取API令牌

先把專案程式碼推送到GitHub，再登入TinaCloud建立專案並連線對應倉庫。進入專案控制檯的Tokens頁面，按用途生成令牌；只需查詢內容時使用只讀令牌，需要編輯內容時確認專案提供並配置了相應寫入權限。不要把令牌提交到倉庫，也不要放進瀏覽器端可公開訪問的程式碼裡。

接著在本地環境變數檔案中儲存Client ID和令牌，例如設定TINA_CLIENT_ID與TINA_TOKEN；變數名要和專案配置保持一致。服務端程式啟動時讀取這些值，並將它們傳給Tina配置中的clientId和token。生產環境也要在部署平臺設定對應變數，然後重新構建，讓後臺能夠連線託管的Content API。

開發階段可以執行TinaCMS本地開發命令，先確認管理後臺能夠開啟、集合列表能夠載入。部署後再檢查生產站點的管理入口和API連線狀態。如果專案使用只讀令牌，查詢可正常工作，但寫入請求可能會被拒絕；遇到權限錯誤時，先核對令牌型別、專案ID、分支和環境變數是否匹配。

第二步：建立和更新內容

呼叫介面前，先檢查schema裡的collection名稱、欄位名、欄位型別和內容路徑。Content API以schema作為資料結構依據，欄位名需要和GraphQL操作中使用的名稱一致。確認服務端已經配置正確的API地址、Client ID和授權令牌，再用GraphQL查詢現有內容，弄清目標檔案的路徑、集合和必填欄位。

建立內容時，使用專案當前版本支援的GraphQL寫入操作，提交新條目的路徑及欄位資料。比如文章集合可能要求標題、正文和釋出日期，缺少必填欄位時操作會失敗。提交前建議在程式裡校驗輸入、生成穩定且唯一的檔案路徑，並處理標題中的空格、特殊字元，避免重複建立或覆蓋了不相關的文章。

更新內容時，先按路徑或唯一標識查到目標條目，再提交需要修改的欄位。若介面要求傳入完整物件，就先讀取原內容併合並修改；若支援區域性更新，也要確認未傳欄位會保留而不是被清空。請求成功後重新查詢一次，檢查返回資料和實際內容檔案，確認標題、正文及後設資料都已按預期儲存。

使用Git版本管理

自動化寫入會影響倉庫內容，因此先在測試分支驗證流程，並確保修改能對應到正確的Git分支。TinaCloud生產環境通常會把編輯儲存到連線的GitHub倉庫；不同部署環境可能使用不同分支配置。正式啟用前檢查提交記錄、作者資訊和構建觸發規則，避免測試文章意外進入線上主分支。

• 先做小範圍測試：用一條草稿驗證建立、更新和查詢流程。
• 保留變更記錄：檢查提交差異，確認只改動目標內容檔案。
• 設定分支保護：重要站點可要求審核後再合併到釋出分支。
• 處理失敗重試：網路超時後先查詢目標檔案是否已寫入，避免直接重試造成重複資料。

第三步：刪除和釋出內容

刪除前先確認目標路徑和條目身份，最好先讀取並記錄當前內容，再呼叫專案所支援的刪除操作。刪除通常不可輕易撤回，批次處理時要先生成待刪除清單、做權限檢查，並限制每次處理數量。完成後重新查詢集合，確認目標內容不再出現，同時檢查Git差異是否僅包含預期刪除。

釋出則要區分“儲存內容”和“網站上線”：API寫入可能只是更新倉庫內容，站點是否更新還取決於分支策略和部署流程。檢查提交是否進入部署分支，再檢視CI構建狀態、預覽頁面和最終頁面。若構建失敗，先修復schema或內容格式，再重新觸發構建；不要僅憑介面返回成功就認定頁面已經發布。

排查問題時，優先檢視服務端日誌中的GraphQL錯誤、欄位校驗資訊和分支配置；日誌不要輸出完整令牌。開發者也可以透過TinaCMS後臺手動儲存一條內容，與API寫入結果對照，快速判斷是權限、schema、檔案路徑還是部署流程的問題。若需要國內可選的輔助內容設計工具，可瞭解墨刀AI；潤滅也可作為相關工具資訊入口，訪問modao.cgref.cn。