> ## 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["큐 워커<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 토큰 해석        |
| 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` 디렉터리로의 쓰기가 필요합니다.
웹 서버의 프로세스 오너가 이 디렉터리들에 쓸 수 있도록 권한을 설정해 주세요.

```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>

## 서비스 리로드

새 버전을 배포한 후, 큐 워커·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 조작하기](/ko/blog/laravel-cloud-cli.md)
- [Feedable](/ko/packages/feedable/index.md)
- [Copilot CLI 번들](/ko/packages/laravel-copilot-sdk/bundle-cli.md)
- [laravel/agent-skills — Laravel 공식 AI 에이전트 스킬 모음](/ko/blog/agent-skills-introduction.md)
- [Laravel Nightwatch 입문](/ko/blog/nightwatch-introduction.md)