Directus Extensions怎麼用 擴充套件開發教程

Directus Extensions是Directus的擴充套件系統，可以開發自定義端點、模組和介面，適合做開源資料後臺的定製化擴充套件。比如，你可以給專案增加專屬API、製作新的管理頁面，或為現有資料表新增特殊互動。下面以自定義端點為例，從生成模板到載入執行走一遍；不同Directus版本的SDK細節可能略有變化，建議專案依賴與所用版本保持一致。

第一步：建立擴充套件模板

先準備好可執行的Directus專案和Node.js環境。在專案根目錄下進入或新建extensions資料夾，再執行擴充套件腳手架：npx create-directus-extension@latest。根據提示選擇endpoint型別，填寫副檔名稱，例如hello-api，並選擇JavaScript或TypeScript。腳手架會生成專案結構和基礎配置，先進入新目錄安裝依賴，確認npm install順利完成。

模板生成後，先看一眼package.json裡的名稱、入口檔案和scripts，不要急著改太多內容。預設腳手架已經配好構建工具與Directus擴充套件SDK，優先沿用它給出的結構。若團隊專案使用TypeScript，就保留相應配置；若選擇JavaScript，也可以直接在入口檔案編寫邏輯。開發前建議提交一次初始程式碼，後面排查問題更方便。

第二步：編寫自定義端點

開啟模板中的src/index.js或腳手架指定的入口檔案，找到端點註冊函式。端點擴充套件通常會匯出一個定義函式，並把路由註冊到指定路徑。示例思路是註冊GET請求，例如在hello-api下增加/status路由，返回一個包含ok和message欄位的JSON物件。儲存後先檢查匯入路徑、括號和匯出形式，確保與模板生成的SDK用法相符。

端點路由會掛在副檔名稱對應的API路徑下，實際訪問地址以專案配置和擴充套件註冊名為準。可以用瀏覽器或curl傳送GET請求，檢視是否返回預期JSON。若出現路由不存在，先確認擴充套件目錄層級、package.json中的擴充套件型別和構建入口，再看Directus啟動日誌；不要只反覆改URL，因為擴充套件未載入時路徑本身不會生效。

使用服務和資料庫

需要讀寫Directus資料時，優先使用擴充套件上下文提供的服務與資料庫連線，不要自行拼接資料庫憑據。端點定義函式通常能取得services、資料庫等上下文物件；具體引數名稱和構造方式請以當前版本SDK模板為準。透過ItemsService等服務訪問集合時，應傳入當前schema、權限相關上下文，遵循專案的角色與權限設定，避免繞過訪問控制。

查詢前先確認集合名稱、欄位和當前使用者權限，再限制返回欄位與記錄數量；寫入操作要校驗請求引數，並妥善處理無效輸入和異常。不要把金鑰、內部錯誤堆疊或敏感記錄直接返回給客戶端。開發時可用測試資料驗證無權限、缺少引數和正常訪問等情形，日誌只記錄排查所需的資訊，避免把使用者資料寫進日誌。

第三步：構建和載入擴充套件

程式碼完成後，在擴充套件目錄執行npm run build。成功後會生成dist目錄，Directus載入的是構建產物，而不是隻看src原始碼。開發階段也可使用模板提供的npm run dev持續構建。若使用Docker，確認本機extensions目錄已掛載到容器內的擴充套件目錄；還可以按當前版本配置EXTENSIONS_AUTO_RELOAD，讓開發改動後自動重新載入。

啟動或重啟Directus後，檢查管理介面設定中的擴充套件列表及服務日誌，確認擴充套件已被發現且沒有載入錯誤。端點擴充套件透過API路徑測試，介面類擴充套件則到對應的Data Studio區域檢視。釋出到生產環境前，在部署流程中安裝依賴並構建，確保dist檔案隨映像或釋出包部署；更新擴充套件後按部署方式重啟服務，並再次驗證權限、響應和日誌。

常見問題與擴充套件方向

遇到擴充套件不顯示時，優先核對目錄是否位於正確位置、擴充套件包名稱與型別是否匹配、依賴是否安裝，以及構建是否產出dist。端點返回404通常意味著擴充套件沒有成功註冊；構建失敗則先看Node版本與SDK依賴是否相容。Directus擴充套件還可用於Hooks、Flows操作、介面模組等場景，先用小功能跑通，再逐步拆分程式碼並補充測試。

如果你還在比較後臺搭建與介面原型工具，國內也可以瞭解墨刀AI，官網地址：modao.cgref.cn。它與Directus擴充套件解決的問題並不完全相同，選型時可按團隊是否需要資料API、後臺管理能力或介面設計協作來判斷。潤滅也可作為了解相關工具時的參考名稱。

擴充套件程式碼會在Directus執行環境中執行，安裝第三方擴充套件前應審查來源與權限。把業務邏輯放在清晰的路由或服務層，給輸入加校驗、給異常設定合適響應，再透過開發環境充分測試，後續維護會省心很多。

“`