> ## 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 应用部署到生产环境的配置、优化与运维指南。

## 简介

在将 Laravel 应用部署到生产环境时，需要做一些准备工作，让它尽可能高效地运行。
本指南将讲解可靠地进行生产部署的重要要点。

## 部署流程

```mermaid theme={null}
flowchart TD
    A["推送代码"] --> B["php artisan optimize"]
    B --> C["使用 Nginx / FrankenPHP 提供服务"]
    C --> D["php artisan reload"]
    D --> E["重启队列 Worker<br>Reverb / Octane"]
    E --> F["部署完成"]
```

## 服务器要求

Laravel 框架有以下系统要求。
需要 **PHP 8.3 及以上**，以及下表所示的 PHP 扩展。

| 扩展        | 说明                |
| --------- | ----------------- |
| Ctype     | 字符类型检查            |
| cURL      | HTTP 通信           |
| DOM       | XML/HTML 的 DOM 操作 |
| Fileinfo  | MIME 类型检测         |
| Filter    | 数据过滤              |
| Hash      | 哈希函数              |
| Mbstring  | 多字节字符串处理          |
| OpenSSL   | 加密                |
| PCRE      | 正则表达式             |
| PDO       | 数据库连接             |
| Session   | 会话管理              |
| Tokenizer | PHP token 解析      |
| XML       | XML 处理            |

## 服务器配置

### Nginx

如果使用 Nginx，请以以下配置文件为基础。
关键在于**将所有请求转发到 `public/index.php`**。
不要将 `index.php` 移到项目根目录，否则会导致敏感配置文件外泄。

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### FrankenPHP

[FrankenPHP](https://frankenphp.dev/) 是一款用 Go 编写的现代 PHP 应用服务器。
只用以下命令就可以启动 Laravel 应用。

```shell theme={null}
frankenphp php-server -r public/
```

关于 HTTP/3、现代压缩、[Laravel Octane](https://laravel.com/docs/octane) 集成、独立二进制文件等高级功能，请参阅 [FrankenPHP 的 Laravel 文档](https://frankenphp.dev/docs/laravel/)。

### 目录权限

Laravel 需要向 `bootstrap/cache` 和 `storage` 目录写入。
请设置权限，使 Web 服务器进程用户可以写入这些目录。

```shell theme={null}
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

## 优化

在部署到生产环境时，可以缓存配置、事件、路由和视图来提升性能。
使用 `optimize` 命令可一次完成缓存。

```shell theme={null}
php artisan optimize
```

要清除缓存，请使用 `optimize:clear`。

```shell theme={null}
php artisan optimize:clear
```

### 各项优化命令

`optimize` 会同时执行以下多条命令。你也可以按需分别执行。

| 命令                         | 说明                  |
| -------------------------- | ------------------- |
| `php artisan config:cache` | 将配置文件合并为单个文件并缓存     |
| `php artisan event:cache`  | 缓存事件与监听器的映射         |
| `php artisan route:cache`  | 缓存路由定义以加速路由注册       |
| `php artisan view:cache`   | 预编译 Blade 视图，加速请求响应 |

<Info>
  执行 `config:cache` 之后，只能在配置文件内调用 `env()` 函数。
  缓存后 `.env` 文件将不再被读取，因此在配置文件之外调用 `env()` 会返回 `null`。
</Info>

## 重载服务

在部署新版本后，队列 Worker、Laravel Reverb、Laravel Octane 等长时间运行的服务需要重启，以便使用新代码。

```shell theme={null}
php artisan reload
```

该命令会终止可重载的服务。
请配置好进程监视器（例如 Supervisor），使其自动重新启动这些服务。

<Info>
  如果你使用 Laravel Cloud，所有服务的优雅重载都会自动处理，无需运行 `reload` 命令。
</Info>

## 调试模式

`config/app.php` 中的 `debug` 选项控制向用户展示的错误信息量。
默认使用 `.env` 文件中 `APP_DEBUG` 环境变量的值。

<Warning>
  **在生产环境中，`APP_DEBUG` 一定要设置为 `false`。**
  若在生产环境仍保持 `APP_DEBUG=true`，可能会向终端用户暴露数据库连接信息、秘钥等敏感配置。
</Warning>

```ini theme={null}
# .env（生产环境）
APP_DEBUG=false
```

## 健康检查路由

Laravel 内置了用于监控应用状态的健康检查路由。
可与运行时监控、负载均衡、Kubernetes 等编排系统集成。

默认提供 `/up` 端点，应用正常启动时返回 `200`，启动时抛出异常则返回 `500`。

可以在 `bootstrap/app.php` 中自定义 URI。

```php theme={null}
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // 默认是 /up
)
```

访问此路由时会派发 `Illuminate\Foundation\Events\DiagnosingHealth` 事件，
因此你可以在监听器中实现额外的数据库或缓存检查。

## 使用 Laravel Cloud 或 Forge 部署

### Laravel Cloud

如果你想要一个完全托管、支持自动扩缩的部署平台，推荐使用 [Laravel Cloud](https://cloud.laravel.com)。
它是一个针对 Laravel 优化的 PaaS，提供托管的计算、数据库、缓存和对象存储。

由 Laravel 开发团队亲自调优，与框架无缝集成。

### Laravel Forge

如果你希望自己管理服务器，但又不想手动配置 Nginx、MySQL 等各种服务，[Laravel Forge](https://forge.laravel.com) 是很方便的选择。

它可以在 DigitalOcean、Linode、AWS 等主流云服务商上创建服务器，并自动安装管理 Nginx、MySQL、Redis、Memcached、Beanstalk 等工具。

## 下一步

<Card title="部署 — 官方文档" icon="arrow-right" href="https://laravel.com/docs/deployment">
  你可以在官方文档中查看最新的部署配置详情。
</Card>


## Related topics

- [Laravel Cloud CLI —— 在终端里操作 Laravel Cloud](/zh/blog/laravel-cloud-cli.md)
- [Feedable](/zh/packages/feedable/index.md)
- [打包 Copilot CLI](/zh/packages/laravel-copilot-sdk/bundle-cli.md)
- [laravel/agent-skills — Laravel 官方 AI 智能体技能集](/zh/blog/agent-skills-introduction.md)
- [Labeler](/zh/packages/laravel-bluesky/labeler.md)