# 快取層

本頁說明圖片經過的四層快取各自的快取鍵、存活時間與失效方式。

## 四層快取

| 層 | 快取鍵 | 存活時間 | 設定位置 |
|---|---|---|---|
| 瀏覽器 | 完整 URL | 7 天（`Cache-Control: public, max-age=604800`） | Nginx `/c/img/` 區塊與 Cloudflare Worker；Express 本身不送此標頭 |
| Cloudflare Worker | 來源 URL＋query string，另附 `X-Custom-Cache-Key` 標頭 | 7 天 | `worker/index.js` |
| Nginx | `proxy_cache` 預設鍵（含 query） | 200／301／302／304 為 7 天，其他 1 分鐘；閒置 30 天淘汰；上限 2 GB | `config/nginx/nodejs.conf` |
| 本機快取檔 | 依參數組成的檔名（見下節） | 無期限 | `GetFromPath.ts` |

## 本機快取檔命名

快取檔位於 `storage/image/cache/`，目錄結構對應 `upload/`。原檔去掉副檔名後依參數追加：

| 參數 | 檔名格式 |
|---|---|
| 有 `s` | `{name}_{s}_{q}.{t}` |
| `w` 與 `h` | `{name}_{w}_{h}_{q}.{t}` |
| 只有 `w` | `{name}_{w}_auto_{q}.{t}` |
| 只有 `h` | `{name}_auto_{h}_{q}.{t}` |
| 皆無 | `{name}_auto_auto_{q}.{t}` |

`?w=800` 產生 `{name}_800_auto_.webp`（未指定品質時為空字串）。`{t}` 為正規化後的格式（`jpeg` → `jpg`，不合法值 → `webp`）。

## 查找順序

```mermaid
graph TB
    A[請求 /c/img/...] --> B{.pdf / .svg？}
    B -->|是| C[串流原檔，不快取]
    B -->|否| D{o = 1？}
    D -->|是| E[串流原檔，不快取]
    D -->|否| F{快取檔存在？}
    F -->|是| G[回傳快取檔]
    F -->|否| H[sharp 轉檔 → 回傳 → 寫入快取檔]
```

## 失效與清除

| 情境 | 結果 |
|---|---|
| 原檔被同名覆寫 | 不會發生：上傳檔名為隨機字串＋時間戳記 |
| 需要清除本機快取 | 手動刪除 `storage/image/cache/` 對應目錄 |
| 需要清除 Nginx 快取 | 刪除容器內 `/var/cache/nginx/images` 後重新載入 Nginx |
| 需要清除 Cloudflare 快取 | 於 Cloudflare Dashboard 清除 |

## 相關頁面

- 參數如何影響輸出：[圖片參數](/zh/api-reference-image)
- 邊緣層設定：[Nginx](/zh/deployment-nginx)、[Cloudflare Worker](/zh/deployment-cloudflare-worker)