메인 콘텐츠로 건너뛰기

소개

Laravel 애플리케이션을 프로덕션 환경에 배포할 때는 가능한 한 효율적으로 동작할 수 있도록 준비가 필요합니다. 이 가이드에서는 프로덕션 배포를 확실하게 수행하기 위한 중요한 포인트를 설명합니다.

배포 플로우

서버 요구 사항

Laravel 프레임워크에는 다음 시스템 요구 사항이 있습니다. PHP 8.3 이상과 아래 PHP 확장 모듈이 필요합니다.
확장 모듈설명
Ctype문자형 체크
cURLHTTP 통신
DOMXML/HTML의 DOM 조작
FileinfoMIME 타입 검출
Filter데이터 필터링
Hash해시 함수
Mbstring멀티바이트 문자열 처리
OpenSSL암호화
PCRE정규 표현식
PDO데이터베이스 접속
Session세션 관리
TokenizerPHP 토큰 해석
XMLXML 처리

서버 설정

Nginx

Nginx를 사용하는 경우, 다음 설정 파일을 베이스로 삼아 주세요. 모든 요청을 public/index.php로 전달하는 것이 중요합니다. index.php를 프로젝트 루트로 이동하지 마세요. 기밀 설정 파일이 외부에 공개됩니다.
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는 Go로 작성된 모던한 PHP 애플리케이션 서버입니다. 다음 명령만으로 Laravel 애플리케이션을 기동할 수 있습니다.
frankenphp php-server -r public/
HTTP/3, 모던한 압축, Laravel Octane 연동, 스탠드얼론 바이너리화 같은 고급 기능은 FrankenPHP의 Laravel 문서를 참조해 주세요.

디렉터리 권한

Laravel은 bootstrap/cachestorage 디렉터리로의 쓰기가 필요합니다. 웹 서버의 프로세스 오너가 이 디렉터리들에 쓸 수 있도록 권한을 설정해 주세요.
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

최적화

프로덕션 환경으로 배포할 때는 설정·이벤트·라우트·뷰를 캐시해 성능을 향상시킵니다. optimize 명령으로 일괄 캐시할 수 있습니다.
php artisan optimize
캐시를 삭제하려면 optimize:clear를 사용합니다.
php artisan optimize:clear

개별 최적화 명령

optimize는 다음 명령을 통합해 실행합니다. 필요에 따라 개별적으로 실행할 수도 있습니다.
명령설명
php artisan config:cache설정 파일을 하나의 파일로 모아 캐시한다
php artisan event:cache이벤트→리스너 매핑을 캐시한다
php artisan route:cache라우트 정의를 캐시해 라우트 등록을 고속화한다
php artisan view:cacheBlade 뷰를 미리 컴파일해 요청을 고속화한다
config:cache를 실행한 후에는 설정 파일 내에서만 env() 함수를 호출해 주세요. 캐시 이후에는 .env 파일이 읽히지 않게 되므로 설정 파일 이외에서 env()를 호출하면 null이 반환됩니다.

서비스 리로드

새 버전을 배포한 후, 큐 워커·Laravel Reverb·Laravel Octane 같은 장시간 동작하는 서비스는 새 코드를 사용하기 위해 재시작이 필요합니다.
php artisan reload
이 명령은 리로드 가능한 서비스를 종료시킵니다. 프로세스 모니터(Supervisor 등)가 자동으로 재시작하도록 설정해 두세요.
Laravel Cloud를 사용하는 경우, 모든 서비스의 그레이스풀 리로드가 자동으로 처리되므로 reload 명령은 불필요합니다.

디버그 모드

config/app.phpdebug 옵션은 오류 정보를 사용자에게 어느 정도까지 표시할지를 제어합니다. 기본적으로 .env 파일의 APP_DEBUG 환경 변수 값이 사용됩니다.
프로덕션 환경에서는 APP_DEBUG를 반드시 false로 설정해 주세요. APP_DEBUG=true 그대로 프로덕션 환경에서 동작시키면 데이터베이스 접속 정보나 비밀 키 같은 기밀 설정 값이 최종 사용자에게 노출될 위험이 있습니다.
# .env(프로덕션 환경)
APP_DEBUG=false

헬스 체크 라우트

Laravel에는 애플리케이션 상태를 감시하기 위한 헬스 체크 라우트가 내장되어 있습니다. 업타임 모니터·로드 밸런서·Kubernetes 같은 오케스트레이션 시스템과 연동할 수 있습니다. 기본적으로 /up 엔드포인트가 준비되어 있으며, 애플리케이션이 정상적으로 기동되어 있으면 200, 기동 시에 예외가 발생하면 500을 반환합니다. bootstrap/app.php에서 URI를 커스터마이징할 수 있습니다.
->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를 추천합니다. 관리형 컴퓨트·데이터베이스·캐시·오브젝트 스토리지를 제공하는, Laravel에 최적화된 PaaS입니다. Laravel 개발 팀이 직접 튜닝하고 있으며, 프레임워크와 원활하게 연동됩니다.

Laravel Forge

직접 서버를 관리하고 싶지만 Nginx나 MySQL 같은 각종 서비스의 세팅에 손이 많이 가는 것은 피하고 싶은 경우, Laravel Forge가 편리합니다. DigitalOcean·Linode·AWS 등 주요 클라우드 프로바이더에 서버를 생성하고, Nginx·MySQL·Redis·Memcached·Beanstalk 같은 도구를 자동으로 설치·관리합니다.

다음 단계

배포 — 공식 문서

공식 문서에서는 최신 배포 설정의 상세 내용을 확인할 수 있습니다.
마지막 수정일 2026년 7월 13일