# 策展 · X (Twitter) 🔥🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：Hayden Bleasel (@haydenbleasel) · 平台：X (Twitter) · 日期：2026-05-26

> 原始來源：https://x.com/haydenbleasel/status/2058955821602811957

## 中文摘要

Files SDK v1.6 正式發布，帶來了可觀測性、大檔案處理及跨供應商工作流的重大升級。

此次更新是 Files SDK 歷來最大的一次改版，重點強化了系統的可觀測性（Observability）、大檔案傳輸支援以及跨儲存供應商的無縫工作流。開發者現在能更精確地監控儲存操作，並透過內建的記憶體適配器（Adapter）簡化測試流程。

**可觀測性與生命週期監控**
透過全新的 Hook 機制，開發者可以即時掌握 SDK 的運作狀態，無需額外封裝呼叫。
- **Hook 機制**：透過 `onAction`、`onError` 與 `onRetry`，開發者能輕鬆記錄儲存活動、測量執行時間、捕捉錯誤，並將重試遙測資料匯入自有的可觀測性層。
- **執行細節**：`onAction` 會在公開呼叫結束時觸發，無論成功或失敗。針對單一鍵值（key）的操作會回報該鍵，陣列形式的批次操作則會回報所有鍵值，並提供聚合後的結果。
- **效能指標**：由於 `onAction` 會回報 `durationMs`（執行耗時），開發者可直接利用此數據進行延遲與吞吐量監控，且該 Hook 為「發送即忘」（fire-and-forget），不會阻塞主操作。

**進階上傳與進度追蹤**
- **即時進度回饋**：`onProgress` 現在支援 `upload` 與 `uploadMany`。對於緩衝主體（如 `File`、`Blob`），它會回報已載入與總位元組數；對於長度未知的 `ReadableStream`，則僅回報已載入位元組，方便開發者實作進度條或即時狀態顯示。
- **Multipart 上傳**：現在內建支援 Multipart 上傳，適用於超過 S3 單一請求限制（5GB）的檔案。透過 `multipart: true` 參數，SDK 會自動將檔案切片並平行上傳，確保大檔案傳輸的穩定性。此功能支援 S3、R2、OneDrive、GCS、Firebase Storage、Azure Blob 及 Dropbox。

**跨供應商傳輸與檔案管理**
- **`transfer()` 跨平台遷移**：此功能允許將物件從一個供應商直接串流傳輸至另一個（例如從 S3 到 R2），無需在記憶體中緩衝整個大檔案。
- **`move()` 操作**：支援檔案重新命名。若供應商支援原生重新命名，則直接呼叫；否則會自動回退至「複製後刪除」的策略。SDK 內建防護機制，若移動目標與來源相同，則視為無操作（no-op），避免檔案被誤刪。
- **`listAll()` 迭代器**：提供非同步迭代器，可自動處理分頁（pagination），開發者無需手動編寫游標迴圈即可遍歷所有檔案。

**開發與測試優化**
- **記憶體適配器**：全新的 `memory()` 適配器基於 `Map` 實作，無需磁碟或網路呼叫。這使得開發者能在測試環境中使用與生產環境相同的 `Files` API，且支援透過 `initial` 參數預載測試資料。
- **位元組範圍下載（Byte Ranges）**：`download` 現在支援 `range` 參數，允許讀取檔案的特定片段。這對於影片播放器的隨機存取（seeking）或斷點續傳功能至關重要。SDK 會驗證供應商是否正確回傳 `206 Partial Content`，若供應商忽略範圍請求並回傳整個檔案，SDK 將會拋出錯誤，避免不必要的頻寬消耗。

**實作範例與指令**
若要安裝最新版本，請根據您的專案環境選擇對應指令：

```bash
# npm
npm install files-sdk

# pnpm
pnpm add files-sdk

# yarn
yarn add files-sdk

# bun
bun add files-sdk
```

若要監控操作指標，可參考以下 `onAction` 的實作方式：

```ts
const files = new Files({
  adapter: s3({ bucket: "uploads" }),
  hooks: {
    onAction(event) {
      metrics.timing(`files.${event.type}.duration`, event.durationMs, { status: event.status });
      metrics.increment(`files.${event.type}.${event.status}`);
    },
  },
});
```

更多詳細資訊與 API 文件，請參閱 [Files SDK 官方文件](https://files-sdk.dev/)。

## 標籤

SDK, 功能更新, Files SDK