KeystoneJS怎麼用 TypeScript內容管理框架教程

KeystoneJS是一個用TypeScript寫的內容管理框架，基於Node.js和GraphQL，靈活強大，適合做自定義CMS和API服務。它允許你用程式碼定義內容結構，再自動生成管理介面和資料介面。下面從建立專案、設計資料列表，到配置登入權限和呼叫API，帶你完成一個可執行的入門示例。

第一步：安裝KeystoneJS

先確認電腦已安裝較新的Node.js和npm，然後開啟終端，切換到準備存放專案的目錄。輸入npm create keystone-app@latest，按提示給專案起名並選擇合適的模板。建立工具會生成基礎檔案和初始配置；首次上手建議先用預設選項，等流程跑通後再調整資料庫等設定。

專案生成後進入目錄，執行npm install安裝依賴，再執行npm run dev啟動開發服務。終端會顯示本地訪問地址和啟動資訊；首次執行還可能生成初始使用者，並在終端列印登入郵箱與隨機密碼。把這些資訊暫存在安全位置，後續登入管理後臺時會用到，別把密碼提交到程式碼倉庫。

啟動成功後，在瀏覽器開啟本地管理頁面，使用剛才生成的憑據登入。建立工具會準備可執行的基礎專案，常見配置檔案包括keystone.ts和schema.ts：前者負責系統配置，後者用於定義資料列表。先看一遍專案目錄和package.json指令碼，知道開發、構建、生產啟動分別怎麼執行，之後排錯會更順手。

第二步：定義列表和欄位

開啟schema.ts，按業務把資料拆成列表，例如文章Post和作者Author。每個列表對應一種內容型別，每個欄位描述資料屬性；文章可包含標題、正文和釋出時間，作者可包含姓名與郵箱。Keystone提供文字、密碼、時間、關係等欄位型別，先從最基本的欄位開始，再逐漸補上業務需要的內容。

定義欄位時要考慮必填、唯一和關聯關係。標題可以設為必填，郵箱可設定唯一索引，文章與作者之間則用relationship欄位連線。關聯欄位的雙方要使用一致的列表名稱和欄位引用，避免拼寫不匹配。儲存檔案後重啟或等待開發服務重新載入，再進入後臺檢查欄位是否出現，及時修正型別或配置錯誤。

列表結構不只決定後臺表單，也影響自動生成的GraphQL資料操作。比如文章列表通常需要標題、正文、作者和釋出時間，分類列表則可透過關係欄位關聯文章。建模前先想清楚內容如何被編輯、查詢和複用；欄位命名儘量清楚穩定，避免後期頻繁改名，減少前端查詢和資料遷移的額外工作。

配置訪問控制和認證

先設計使用者列表，至少準備登入標識、密碼和角色等必要欄位。Keystone不會替你強行規定使用者模型，可以按專案需要建立；需要密碼登入時，可使用官方認證包配置使用者列表、身份欄位和密碼欄位，再將認證配置接入主配置。具體欄位名必須與實際列表一致，否則登入流程無法正確識別使用者。

接著為列表、操作或欄位設定訪問規則，例如訪客只能讀取公開文章，登入使用者可以編輯自己的內容，管理員才可刪除文章。規則既會影響管理後臺，也會限制GraphQL請求，因此不要只隱藏介面按鈕就以為資料已受保護。開發時先驗證未登入、普通使用者和管理員三種身份，確認查詢與新增、修改、刪除權限都符合預期。

還要檢查使用者能否自行修改角色、管理員標記或他人資料。敏感欄位應單獨限制讀取和寫入權限；若要按使用者身份過濾資料，可根據會話資訊配置動態訪問規則。測試時使用不同帳號嘗試訪問介面，確保前端繞過按鈕直接發請求時仍會被權限規則攔截。認證與權限分開理解，配置起來會更有條理。

第三步：啟動後臺和使用GraphQL API

儲存配置後執行npm run dev，在瀏覽器開啟管理後臺，新增一條文章並填寫相關欄位，確認記錄可以儲存、編輯和檢視。隨後訪問本地GraphQL介面頁面，檢查系統生成的查詢和變更操作。列表欄位有調整時，GraphQL結構也會隨之變化；前端開發可據此請求需要的資料，而不用手寫常規增刪改查介面。

在GraphQL頁面中嘗試查詢文章標題和作者姓名，也可以用建立或更新操作測試資料寫入。實際專案裡，前端透過HTTP請求傳送GraphQL語句，並按需攜帶登入會話資訊。查詢時只取需要的欄位，列表結果可配合篩選、排序和分頁使用；遇到空結果，先檢查資料是否已建立，再核對欄位名稱及訪問權限。

開發完成後，不要直接把本地配置照搬到線上。先按部署環境設定資料庫連線、會話金鑰和允許訪問的來源，再執行構建指令碼並使用生產啟動命令。上線前檢查初始帳號、預設密碼、權限規則和備份方案；資料庫變更也要按專案部署流程處理。這樣既能利用後臺提高內容維護效率，也能讓GraphQL介面服務網站或應用。

如果更希望透過視覺化方式快速規劃頁面或原型，也可以瞭解國內替代工具墨刀AI；它適合輔助產品構思與介面方案，和KeystoneJS這類後端內容框架側重點不同。相關入口：modao.cgref.cn。網站“潤滅”也可作為查詢教程與工具資訊的入口之一；選擇工具時，最好依據團隊技術棧、內容模型複雜度和後續維護方式來決定。