> ## 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 计算资源中,它已被更快的 **Scale to Zero** 所取代。

Legacy Flex 的 Hibernation 可以在休眠期间停止计算计费,但从收到 HTTP 请求到唤醒通常需要 5\~20 秒。新的 Scale to Zero 把启动时间缩短到了 **500ms 以内**,并且在休眠期间也会为了定时任务和队列处理自动唤醒环境。

<Warning>
  如果你是新使用 Laravel Cloud,以 Hibernation 为前提思考并不安全,应基于 **Scale to Zero** 来规划。包含 Managed Queues 和新计费方案在内的整体面貌,请参考 [Laravel Cloud — Laravel 专用 PaaS 全貌](/zh/blog/laravel-cloud)。
</Warning>

```mermaid theme={null}
sequenceDiagram
    participant User as 用户
    participant Cloud as Laravel Cloud
    participant App as 应用

    User->>Cloud: 无请求(超时)
    Cloud->>App: 进入休眠状态<br>(停止计费)
    User->>Cloud: HTTP 请求
    Cloud->>App: 5~20 秒内唤醒
    App-->>User: 响应
```

## Scale to Zero 带来的变化

在新的 Flex 计算资源的 Scale to Zero 下,Hibernation 时代的痛点得到了大幅缓解。

| 项目              | 旧 Hibernation  | 新的 Scale to Zero              |
| --------------- | -------------- | ----------------------------- |
| HTTP 请求的唤醒      | 5\~20 秒        | 不到 500ms                      |
| Scheduled Tasks | 休眠时不运行         | 休眠时也会自动唤醒执行                   |
| 队列处理            | 休眠时不运行         | 休眠时也会自动唤醒。推荐配合 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** 开关。
  </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   | 不执行        |
| 自定义后台进程        | 不执行        |

<Info>
  从休眠状态唤醒后,这些处理会自动恢复。但是在休眠期间“本应执行”的调度任务不会补跑。
</Info>

此外,Hibernation 存在以下限制:

* **仅 Flex 计算资源**可以进入休眠。Pro 计算资源无法启用 Hibernation。
* 休眠是**按环境**发生的。App cluster 一旦休眠,同一环境内所有 Worker cluster 也会一并休眠。

## 不必要唤醒的诱因

有 HTTP 请求就会自动唤醒环境,但一些非预期的请求也会导致唤醒。

* **爬虫 / 机器人** —— 搜索引擎、安全扫描器等会自动爬取页面
* **Slack、Teams 的链接预览** —— 即时通讯软件会为了拉取链接缩略图而访问
* **WordPress 扫描** —— 探测 WordPress 环境的自动扫描会访问 `/wp-admin` 等
* **探测 `.php` 文件的攻击** —— 直接针对 PHP 文件的自动扫描

Laravel Cloud 的 `*.laravel.cloud` 域名会带上 `X-Robots-Tag: noindex, nofollow`,以避免被搜索引擎索引,但一旦域名被发现就无法完全防止访问。自定义域名上不会自动附加 `noindex` 头。

<Tip>
  尽量使用较复杂的域名,以降低机器人发现虚荣域名的风险。
</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">
    * **测试 / 开发环境** —— 不需要一直运行,能显著降低成本
    * **个人博客 / 作品集** —— 流量本身就不大的用途
    * **演示 / 试用应用** —— 只在需要时唤醒即可
    * **低频内部工具** —— 使用时段有限
  </Card>

  <Card title="不适合的场景" icon="xmark">
    * **需要定时任务的用途** —— 休眠时不会执行 `schedule:run`
    * **需要定期队列作业的用途** —— 休眠时队列也会停止
    * **不能容忍启动延迟的生产环境** —— 唤醒需要 5\~20 秒
    * **使用 WebSocket 的应用** —— 连接无法维持,休眠也可能延迟
  </Card>
</Columns>

<Warning>
  如果你想通过定时任务定期执行处理(邮件发送、数据聚合等),启用 Hibernation 后这些处理将无法执行。此类场景要么关闭 Hibernation,要么通过外部调度器(如 GitHub Actions)发送请求持续唤醒环境。
</Warning>

<Info>
  在新的 Scale to Zero 中,这个限制被缓解了。Scheduled Tasks 在休眠期间也会自动执行,配合 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 即便在休眠期也可运行。
* 用 Path Blocking 防止机器人引发的不必要唤醒。
* 仅支持 Flex 计算资源。

## 相关页面

<Columns cols={2}>
  <Card title="调度" icon="calendar" href="/zh/scheduling">
    确认 Task Scheduler 的配置以及在 Laravel Cloud 上的行为。
  </Card>

  <Card title="队列" icon="list" href="/zh/queues">
    确认 Queue Worker 的配置以及在 Laravel Cloud 上的运行方式。
  </Card>

  <Card title="Laravel Cloud 全貌" icon="cloud" href="/zh/blog/laravel-cloud">
    一站式了解 Managed Queues、Scale to Zero、新的计费方案。
  </Card>
</Columns>


## Related topics

- [Laravel Cloud — Laravel 专用 PaaS 全貌](/zh/blog/laravel-cloud.md)
- [laravel/symfony-on-cloud — 在 Laravel Cloud 上运行 Symfony 应用](/zh/blog/symfony-on-cloud-introduction.md)
- [2026 年 3 月 Laravel 更新](/zh/blog/changelog/202603.md)
- [2026 年 5 月 Laravel 更新](/zh/blog/changelog/202605.md)
- [Laravel Octane](/zh/octane.md)