소개
Laravel 애플리케이션을 프로덕션 환경에 배포할 때는 가능한 한 효율적으로 동작할 수 있도록 준비가 필요합니다. 이 가이드에서는 프로덕션 배포를 확실하게 수행하기 위한 중요한 포인트를 설명합니다.배포 플로우
서버 요구 사항
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를 프로젝트 루트로 이동하지 마세요. 기밀 설정 파일이 외부에 공개됩니다.
FrankenPHP
FrankenPHP는 Go로 작성된 모던한 PHP 애플리케이션 서버입니다. 다음 명령만으로 Laravel 애플리케이션을 기동할 수 있습니다.디렉터리 권한
Laravel은bootstrap/cache와 storage 디렉터리로의 쓰기가 필요합니다.
웹 서버의 프로세스 오너가 이 디렉터리들에 쓸 수 있도록 권한을 설정해 주세요.
최적화
프로덕션 환경으로 배포할 때는 설정·이벤트·라우트·뷰를 캐시해 성능을 향상시킵니다.optimize 명령으로 일괄 캐시할 수 있습니다.
optimize:clear를 사용합니다.
개별 최적화 명령
optimize는 다음 명령을 통합해 실행합니다. 필요에 따라 개별적으로 실행할 수도 있습니다.
| 명령 | 설명 |
|---|---|
php artisan config:cache | 설정 파일을 하나의 파일로 모아 캐시한다 |
php artisan event:cache | 이벤트→리스너 매핑을 캐시한다 |
php artisan route:cache | 라우트 정의를 캐시해 라우트 등록을 고속화한다 |
php artisan view:cache | Blade 뷰를 미리 컴파일해 요청을 고속화한다 |
config:cache를 실행한 후에는 설정 파일 내에서만 env() 함수를 호출해 주세요.
캐시 이후에는 .env 파일이 읽히지 않게 되므로 설정 파일 이외에서 env()를 호출하면 null이 반환됩니다.서비스 리로드
새 버전을 배포한 후, 큐 워커·Laravel Reverb·Laravel Octane 같은 장시간 동작하는 서비스는 새 코드를 사용하기 위해 재시작이 필요합니다.Laravel Cloud를 사용하는 경우, 모든 서비스의 그레이스풀 리로드가 자동으로 처리되므로
reload 명령은 불필요합니다.디버그 모드
config/app.php의 debug 옵션은 오류 정보를 사용자에게 어느 정도까지 표시할지를 제어합니다.
기본적으로 .env 파일의 APP_DEBUG 환경 변수 값이 사용됩니다.
헬스 체크 라우트
Laravel에는 애플리케이션 상태를 감시하기 위한 헬스 체크 라우트가 내장되어 있습니다. 업타임 모니터·로드 밸런서·Kubernetes 같은 오케스트레이션 시스템과 연동할 수 있습니다. 기본적으로/up 엔드포인트가 준비되어 있으며, 애플리케이션이 정상적으로 기동되어 있으면 200, 기동 시에 예외가 발생하면 500을 반환합니다.
bootstrap/app.php에서 URI를 커스터마이징할 수 있습니다.
Illuminate\Foundation\Events\DiagnosingHealth 이벤트가 발행되므로,
데이터베이스나 캐시의 추가 체크를 리스너에서 구현할 수 있습니다.
Laravel Cloud 또는 Forge로 배포
Laravel Cloud
완전 관리형 자동 스케일 배포 플랫폼을 찾는다면 Laravel Cloud를 추천합니다. 관리형 컴퓨트·데이터베이스·캐시·오브젝트 스토리지를 제공하는, Laravel에 최적화된 PaaS입니다. Laravel 개발 팀이 직접 튜닝하고 있으며, 프레임워크와 원활하게 연동됩니다.Laravel Forge
직접 서버를 관리하고 싶지만 Nginx나 MySQL 같은 각종 서비스의 세팅에 손이 많이 가는 것은 피하고 싶은 경우, Laravel Forge가 편리합니다. DigitalOcean·Linode·AWS 등 주요 클라우드 프로바이더에 서버를 생성하고, Nginx·MySQL·Redis·Memcached·Beanstalk 같은 도구를 자동으로 설치·관리합니다.다음 단계
배포 — 공식 문서
공식 문서에서는 최신 배포 설정의 상세 내용을 확인할 수 있습니다.