本指南將引導您在基於 Express.js 的 blocklet 中設定 @blocklet/uploader-server 套件。此套件提供了必要的伺服器端中介軟體，以處理由 @blocklet/uploader 前端元件發起的檔案上傳。
雖然前端的 @blocklet/uploader 可以與任何支援 Tus 可續傳上傳協定的自訂後端一起使用，但 @blocklet/uploader-server 提供了一個立即可用的整合解決方案，可處理本地檔案儲存、元資料處理以及過期上傳的清理。
上傳流程概覽
下圖說明了當使用者使用前端元件和後端伺服器中介軟體上傳檔案時的典型資料流程。
步驟 1：安裝
首先，將此套件新增至您的 blocklet 的依賴項中。
pnpm add @blocklet/uploader-server步驟 2：基本設定
此套件的主要匯出是 initLocalStorageServer。此函數會建立一個 Express 中介軟體，用於處理檔案上傳並將其儲存到本地檔案系統中。
在您的 blocklet 中建立一個新的路由檔案 (例如 routes/uploads.js)，並新增以下基本設定：
Basic upload endpoint
import express from 'express';
import { initLocalStorageServer } from '@blocklet/uploader-server';
const router = express.Router();
// 初始化上傳器伺服器中介軟體
const localStorageServer = initLocalStorageServer({
path: process.env.UPLOAD_DIR, // 用於儲存上傳檔案的目錄
express,
});
// 掛載上傳器中介軟體以處理此路由的所有請求
router.use('/', localStorageServer.handle);
export default router;在這個最小化的設定中：
- 我們匯入了
initLocalStorageServer。 - 我們用一個
path選項來呼叫它，該選項指定了伺服器上儲存檔案的目錄。這應該是一個絕對路徑。 - 我們將
express物件本身傳遞給中介軟體。 - 最後，我們將返回的處理常式掛載到我們的路由器上。
現在，您可以在您的主 app.js 檔案中掛載此路由器：
app.js
// ... 其他匯入
import uploadRouter from './routes/uploads';
// ... 應用程式設定
app.use('/api/uploads', uploadRouter);完成這些設定後，您的後端現在已準備好在 /api/uploads 端點接收檔案上傳。
步驟 3：處理上傳完成
僅僅儲存檔案是不夠的；您通常需要將其元資料儲存到資料庫，並向前端返回一個可公開存取的 URL。這是透過 onUploadFinish 回呼來完成的。
onUploadFinish 函數在檔案成功且完整地上傳到伺服器後執行。
以下是一個更完整的範例，示範如何使用它：
Full backend example
import { initLocalStorageServer } from '@blocklet/uploader-server';
import express from 'express';
import url from 'url';
import path from 'path';
// 假設您有一個用於上傳的資料庫模型
// import Upload from '../models/upload';
const router = express.Router();
const localStorageServer = initLocalStorageServer({
path: process.env.UPLOAD_DIR,
express,
onUploadFinish: async (req, res, uploadMetadata) => {
// 1. 從完成的上傳中解構元資料
const {
id: filename, // 磁碟上唯一的隨機檔案名稱
size,
metadata: { filename: originalname, filetype: mimetype },
} = uploadMetadata;
// 2. 建構檔案的公開 URL
const publicUrl = new URL(process.env.APP_URL);
publicUrl.pathname = path.join('/api/uploads', filename);
// 3. (可選但建議) 將檔案元資料儲存到您的資料庫
/*
const doc = await Upload.insert({
mimetype,
originalname,
filename,
size,
url: publicUrl.href,
createdAt: new Date().toISOString(),
createdBy: req.user.did,
});
*/
// 4. 向前端返回一個 JSON 物件。此物件將在
// 前端的 onUploadSuccess 回呼中可用。
const responseData = {
url: publicUrl.href,
// ...doc, // 如果您建立了資料庫記錄，請包含它
};
return responseData;
},
});
// 掛載處理常式。任何用於身份驗證的中介軟體 (如 `user`, `auth`)
// 都應放在處理常式之前。
router.use('/', localStorageServer.handle);
export default router;關鍵點：
uploadMetadata：此物件包含有關已上傳檔案的所有資訊，包括其唯一 ID (也是其在磁碟上的檔案名稱)、大小以及從用戶端傳送的原始元資料 (如originalname和mimetype)。- 資料庫整合：此回呼是將已上傳檔案與您應用程式中的使用者或其他資源連結起來，並在資料庫中建立記錄的最佳位置。
- 傳回值：
onUploadFinish傳回的物件會被序列化為 JSON 並作為回應傳送給前端。前端的onUploadSuccess回呼將收到此物件，從而得知已上傳檔案的最終 URL。
後續步驟
完成後端設定後，您就可以探索更多進階功能和自訂選項了。