> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Cloud Hibernation（自動休眠）

> 解說 Laravel Cloud 自動休眠功能的機制、啟用方式、限制事項，以及以 Path Blocking 避免不必要喚醒的做法。

## 什麼是 Hibernation

Laravel Cloud 的 **Hibernation（自動休眠）** 是舊有機制，在一段時間內若無 HTTP 請求就把環境切換到休眠狀態。
在目前的新 Flex Compute 中，後繼者是更快速的 **Scale to Zero**。

Legacy Flex 的 Hibernation 可讓休眠期間停止 Compute 計費，但收到 HTTP 請求後通常需要 5〜20 秒才能恢復。新的 Scale to Zero 啟動時間縮短到**500ms 內**，而且即便在 sleep 中，環境仍會為排程任務或佇列處理自動啟動。

<Warning>
  若你是新使用 Laravel Cloud，較安全的做法是以 **Scale to Zero** 為前提思考，而非 Hibernation。包含 Managed Queues 與新方案在內的整體樣貌，請參考 [Laravel Cloud — Laravel 專用 PaaS 全貌](/zh-TW/blog/laravel-cloud)。
</Warning>

```mermaid theme={null}
sequenceDiagram
    participant User as 使用者
    participant Cloud as Laravel Cloud
    participant App as 應用

    User->>Cloud: 沒有請求（timeout）
    Cloud->>App: 切換至休眠<br>（停止計費）
    User->>Cloud: HTTP 請求
    Cloud->>App: 5〜20 秒後恢復
    App-->>User: 回應
```

## Scale to Zero 改變了什麼

新 Flex Compute 的 Scale to Zero 大幅改善了過去 Hibernation 的痛點。

| 項目              | 舊 Hibernation  | 新 Scale to Zero                   |
| --------------- | -------------- | --------------------------------- |
| HTTP 請求恢復時間     | 5〜20 秒         | 500ms 內                           |
| Scheduled Tasks | 休眠中不執行         | Sleep 中也會自動啟動並執行                  |
| 佇列處理            | 休眠中不執行         | Sleep 中也會自動啟動。建議搭配 Managed Queues |
| 建議用途            | 舊 Flex 環境的節省用途 | 目前的標準架構                           |

<Info>
  過去 Hibernation 在休眠期間會導致排程任務、佇列不運作。Scale to Zero 解決了此問題，特別是佇列若採用 Managed Queues，即使 App cluster 在沈睡也能安全持續。
</Info>

## 舊 Hibernation 的啟用步驟

<Steps>
  <Step title="開啟 App compute cluster">
    在環境的基礎架構畫布儀表板中點選 App compute cluster。
  </Step>

  <Step title="啟用 Hibernation">
    將 **Hibernation** 開關切為 On。
  </Step>

  <Step title="儲存並重新部署">
    點選 **Save and Redeploy** 以套用變更。

    <Warning>
      只變更設定不會生效，必須執行 Save and Redeploy。
    </Warning>
  </Step>
</Steps>

<Tip>
  若在現行環境要新啟用，請使用 App compute cluster 的 **Scale to Zero** 開關。以下的限制事項主要是針對舊 Hibernation / Legacy Flex 的說明。
</Tip>

## 舊 Hibernation 休眠中的限制

Hibernation 啟用且環境處於休眠時，以下功能不會運作。

| 功能             | 休眠中的行為     |
| -------------- | ---------- |
| HTTP 請求處理      | 停止（恢復後才處理） |
| Task Scheduler | 不執行        |
| Queue Worker   | 不執行        |
| 自訂背景 Process   | 不執行        |

<Info>
  從休眠恢復後這些處理會自動重啟。但在休眠期間「本該執行」的排程 Job 不會補跑。
</Info>

此外，Hibernation 尚有下列限制：

* **只有 Flex Compute** 可以休眠。Pro Compute 無法啟用 Hibernation。
* 休眠是**以環境為單位**進行。App cluster 休眠時，同環境中的所有 Worker cluster 也會休眠。

## 不必要喚醒的原因

只要有 HTTP 請求環境就會自動喚醒，但也常因非預期的請求而喚醒。

* **Bot 與 Crawler** — 搜尋引擎或安全掃描等自動爬頁
* **Slack 或 Teams 的連結預覽** — 通訊軟體為抓取連結縮圖而存取
* **WordPress 掃描** — 尋找 WordPress 環境的自動掃描存取 `/wp-admin` 等
* **尋找 `.php` 檔的攻擊** — 直接鎖定 PHP 檔的自動掃描

Laravel Cloud 的 `*.laravel.cloud` 網域會加上 `X-Robots-Tag: noindex, nofollow` 避免被搜尋引擎索引，但一旦網域被發現就難以避免。自訂網域則不會加上 `noindex` 標頭。

<Tip>
  儘量使用不易被找到的複雜網域名稱，可降低 Bot 發現虛榮網域的風險。
</Tip>

## 用 Path Blocking 防止不必要喚醒

**Path Blocking** 功能可讓對特定副檔名或路徑的請求在休眠期間不處理直接被封鎖，避免 WordPress 掃描或針對 PHP 檔的攻擊觸發喚醒。

預設會封鎖的副檔名與路徑如下。

**被封鎖的副檔名：**

```
.php, .php3, .php4, .php5, .php6, .php7, .php8,
.phtml, .pht, .phps, .env, .git
```

**被封鎖的路徑：**

```
/wp-admin, /wp-content, /wp-includes, /wp-json
```

這些請求即使環境休眠中也不會喚醒應用，會直接回應。

<Info>
  Laravel 的一般路由不會使用附帶 `.php` 副檔名的請求，因此封鎖這些不會影響應用運作。
</Info>

## 舊 Hibernation 適合與不適合的用途

<Columns cols={2}>
  <Card title="適合的用途" icon="check">
    * **staging、開發環境** — 不需 24 小時運作，可大幅節費
    * **個人部落格、作品集** — 流量少的用途
    * **Demo、測試用 App** — 只在需要時喚醒即可
    * **低頻率內部工具** — 使用時間有限
  </Card>

  <Card title="不適合的用途" icon="xmark">
    * **使用排程任務的用途** — 休眠中 `schedule:run` 不會執行
    * **需要定期佇列 Job 的用途** — 休眠中佇列也停擺
    * **無法容忍啟動延遲的正式環境** — 恢復需 5〜20 秒
    * **使用 WebSocket 的應用** — 無法維持連線，亦可能造成休眠延遲
  </Card>
</Columns>

<Warning>
  若要以 Task Scheduler 定期執行處理（例如寄信、資料統整），啟用 Hibernation 會導致處理不執行。此類用途需關閉 Hibernation，或設計為由外部排程器（GitHub Actions 等）發送請求持續喚醒環境。
</Warning>

<Info>
  在新 Scale to Zero 中此限制已放寬。Scheduled Tasks 在 sleep 中也會自動執行，佇列處理若採用 Managed Queues 亦不受 App cluster 休眠影響。
</Info>

## 總結

Hibernation 在 Legacy Flex 中仍可用於節省成本，但目前 Scale to Zero 更為實用。

* Legacy Flex 只在運作時計費，逾時後自動休眠。
* 舊 Hibernation 恢復時間為 5〜20 秒。
* 新 Scale to Zero 可在 500ms 內啟動。
* Scale to Zero 中 Scheduled Tasks 與 Managed Queues 於 sleep 期間仍運作。
* Path Blocking 可防止 Bot 導致的不必要喚醒。
* 僅 Flex Compute 支援。

## 相關頁面

<Columns cols={2}>
  <Card title="排程" icon="calendar" href="/zh-TW/scheduling">
    確認 Task Scheduler 的設定與在 Laravel Cloud 的行為。
  </Card>

  <Card title="佇列" icon="list" href="/zh-TW/queues">
    確認 Queue Worker 的設定與在 Laravel Cloud 的運作方式。
  </Card>

  <Card title="Laravel Cloud 全貌" icon="cloud" href="/zh-TW/blog/laravel-cloud">
    一次確認 Managed Queues、Scale to Zero 與新的方案。
  </Card>
</Columns>


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [Laravel Cloud — Laravel 專用 PaaS 全貌](/zh-TW/blog/laravel-cloud.md)
- [博客](/zh-CN/blog/index.md)
- [laravel/symfony-on-cloud — 在 Laravel Cloud 上執行 Symfony 應用](/zh-TW/blog/symfony-on-cloud-introduction.md)
- [2026 年 5 月 Laravel 更新](/zh-TW/blog/changelog/202605.md)