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

# Despliegue

> Guía de configuración, optimización y operación para desplegar una aplicación Laravel en producción

## Introducción

Al desplegar una aplicación Laravel en producción, es necesario prepararla para que funcione con la mayor eficiencia posible.
Esta guía explica los aspectos clave para realizar despliegues de producción de forma fiable.

## Flujo de despliegue

```mermaid theme={null}
flowchart TD
    A["Push del código"] --> B["php artisan optimize"]
    B --> C["Servir con Nginx / FrankenPHP"]
    C --> D["php artisan reload"]
    D --> E["Reinicio de workers de cola<br>Reverb / Octane"]
    E --> F["Despliegue completado"]
```

## Requisitos del servidor

El framework Laravel tiene los siguientes requisitos del sistema.
Necesitas **PHP 8.3 o superior** y las siguientes extensiones de PHP.

| Extensión | Descripción                         |
| --------- | ----------------------------------- |
| Ctype     | Comprobación de tipos de caracteres |
| cURL      | Comunicación HTTP                   |
| DOM       | Manipulación del DOM de XML/HTML    |
| Fileinfo  | Detección de tipo MIME              |
| Filter    | Filtrado de datos                   |
| Hash      | Funciones hash                      |
| Mbstring  | Procesamiento de cadenas multibyte  |
| OpenSSL   | Cifrado                             |
| PCRE      | Expresiones regulares               |
| PDO       | Conexión a base de datos            |
| Session   | Gestión de sesiones                 |
| Tokenizer | Análisis de tokens de PHP           |
| XML       | Procesamiento XML                   |

## Configuración del servidor

### Nginx

Si usas Nginx, parte del siguiente archivo de configuración.
Es esencial **reenviar todas las solicitudes a `public/index.php`**.
No muevas `index.php` a la raíz del proyecto: expondrías archivos de configuración sensibles.

```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/) es un servidor de aplicaciones PHP moderno escrito en Go.
Puedes iniciar una aplicación Laravel solo con este comando:

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

Para funcionalidades avanzadas como HTTP/3, compresión moderna, integración con [Laravel Octane](https://laravel.com/docs/octane) o binarios autónomos, consulta la [documentación de Laravel en FrankenPHP](https://frankenphp.dev/docs/laravel/).

### Permisos de directorios

Laravel necesita escritura en los directorios `bootstrap/cache` y `storage`.
Configura los permisos para que el propietario del proceso del servidor web pueda escribir en ellos.

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

## Optimización

Al desplegar en producción, mejora el rendimiento cacheando configuración, eventos, rutas y vistas.
Puedes cachearlo todo de golpe con `optimize`.

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

Para limpiar la caché usa `optimize:clear`.

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

### Comandos de optimización individuales

`optimize` ejecuta los siguientes comandos en bloque. También puedes ejecutarlos por separado si es necesario.

| Comando                    | Descripción                                               |
| -------------------------- | --------------------------------------------------------- |
| `php artisan config:cache` | Combina los archivos de configuración en uno y los cachea |
| `php artisan event:cache`  | Cachea el mapeo eventos → listeners                       |
| `php artisan route:cache`  | Cachea la definición de rutas y acelera su registro       |
| `php artisan view:cache`   | Precompila las vistas Blade y acelera las solicitudes     |

<Info>
  Después de ejecutar `config:cache`, llama a `env()` únicamente dentro de los archivos de configuración.
  Una vez cacheado, el archivo `.env` deja de leerse, y si llamas a `env()` fuera de los archivos de configuración devolverá `null`.
</Info>

## Recarga de servicios

Tras desplegar una nueva versión, los servicios de larga duración como workers de cola, Laravel Reverb o Laravel Octane necesitan reiniciarse para usar el nuevo código.

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

Este comando finaliza los servicios recargables.
Asegúrate de tener un monitor de procesos (como Supervisor) que los reinicie automáticamente.

<Info>
  Si utilizas Laravel Cloud, la recarga elegante de todos los servicios se gestiona automáticamente, por lo que no necesitas el comando `reload`.
</Info>

## Modo debug

La opción `debug` de `config/app.php` controla cuánta información de error se muestra al usuario.
Por defecto usa el valor de la variable de entorno `APP_DEBUG` del archivo `.env`.

<Warning>
  **En producción, `APP_DEBUG` debe ser siempre `false`.**
  Si `APP_DEBUG=true` en producción, hay riesgo de exponer valores sensibles como credenciales de base de datos o claves privadas al usuario final.
</Warning>

```ini theme={null}
# .env (producción)
APP_DEBUG=false
```

## Ruta de health check

Laravel incluye una ruta de health check para monitorizar el estado de la aplicación.
Se integra con monitores de uptime, balanceadores de carga y sistemas de orquestación como Kubernetes.

Por defecto se expone el endpoint `/up`, que devuelve `200` si la aplicación arrancó correctamente o `500` si ocurrió una excepción durante el arranque.

Puedes personalizar el URI en `bootstrap/app.php`.

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

Cuando se accede a esta ruta se emite el evento `Illuminate\Foundation\Events\DiagnosingHealth`, por lo que puedes implementar comprobaciones adicionales (base de datos, caché, etc.) en un listener.

## Despliegue con Laravel Cloud o Forge

### Laravel Cloud

Si buscas una plataforma de despliegue totalmente gestionada con autoescalado, [Laravel Cloud](https://cloud.laravel.com) es la opción recomendada.
Es una PaaS optimizada para Laravel que ofrece compute, base de datos, caché y almacenamiento de objetos gestionados.

Está afinada directamente por el equipo de desarrollo de Laravel y se integra con el framework de forma transparente.

### Laravel Forge

Si prefieres gestionar tus propios servidores pero sin dedicar tiempo a instalar servicios como Nginx o MySQL, [Laravel Forge](https://forge.laravel.com) es de gran ayuda.

Crea servidores en los principales proveedores cloud (DigitalOcean, Linode, AWS, etc.) e instala y gestiona automáticamente herramientas como Nginx, MySQL, Redis, Memcached, Beanstalk y más.

## Próximos pasos

<Card title="Despliegue — Documentación oficial" icon="arrow-right" href="https://laravel.com/docs/deployment">
  Consulta la documentación oficial para conocer los últimos detalles de configuración de despliegue.
</Card>


## Related topics

- [Laravel Cloud CLI — Operar Laravel Cloud desde la terminal](/es/blog/laravel-cloud-cli.md)
- [Empaquetar Copilot CLI](/es/packages/laravel-copilot-sdk/bundle-cli.md)
- [Feedable](/es/packages/feedable/index.md)
- [laravel/agent-skills — Colección oficial de skills para agentes de IA de Laravel](/es/blog/agent-skills-introduction.md)
- [Introducción a Laravel Nightwatch](/es/blog/nightwatch-introduction.md)