배포

번역일: 2026년 6월 20일

배포

소개
서버 요구사항
서버 설정
최적화
서비스 재시작
디버그 모드
헬스 라우트
Laravel Cloud 또는 Forge로 배포

소개

Laravel 애플리케이션을 프로덕션 환경에 배포할 준비가 됐다면, 애플리케이션이 최대한 효율적으로 동작할 수 있도록 몇 가지 사항을 점검해야 합니다. 이 문서에서는 Laravel 애플리케이션을 올바르게 배포하기 위한 핵심 체크포인트를 안내합니다.

서버 요구사항

Laravel 프레임워크가 동작하려면 웹 서버에 아래 조건이 충족되어야 합니다. 최소 PHP 버전과 필수 익스텐션을 사전에 확인하세요.

PHP >= 8.2
Ctype PHP Extension
cURL PHP Extension
DOM PHP Extension
Fileinfo PHP Extension
Filter PHP Extension
Hash PHP Extension
Mbstring PHP Extension
OpenSSL PHP Extension
PCRE PHP Extension
PDO PHP Extension
Session PHP Extension
Tokenizer PHP Extension
XML PHP Extension

서버 설정

Nginx

Nginx를 사용하는 서버에 배포한다면, 아래 설정 파일을 출발점으로 활용할 수 있습니다. 실제 서버 환경에 맞게 적절히 수정해서 사용하세요. 서버 관리가 부담스럽다면 Laravel Cloud와 같은 완전 관리형 플랫폼 사용을 고려해 보세요.

아래 설정에서 확인할 수 있듯이, 웹 서버는 모든 요청을 애플리케이션의 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.2-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를 사용해 Laravel 애플리케이션을 서비스할 수도 있습니다. FrankenPHP는 Go 언어로 작성된 최신 PHP 애플리케이션 서버입니다. php-server 명령 하나로 간단하게 시작할 수 있습니다.

frankenphp php-server -r public/

Laravel Octane 통합, HTTP/3 지원, 최신 압축 알고리즘, Laravel 애플리케이션을 독립 실행 바이너리로 패키징하는 기능 등 FrankenPHP의 고급 기능을 활용하려면 FrankenPHP 공식 Laravel 문서를 참고하세요.

디렉터리 권한

Laravel은 bootstrap/cache와 storage 디렉터리에 파일을 기록해야 합니다. 웹 서버 프로세스를 실행하는 사용자가 이 두 디렉터리에 쓰기 권한을 가지고 있는지 반드시 확인하세요.

최적화

프로덕션 배포 시에는 설정, 이벤트, 라우트, 뷰 등 다양한 파일을 캐시해 두면 성능을 크게 향상시킬 수 있습니다. Laravel은 이 모든 캐시 작업을 한 번에 처리하는 편리한 optimize Artisan 명령을 제공합니다. 배포 프로세스의 일부로 이 명령을 실행하는 것을 권장합니다.

php artisan optimize

optimize:clear 명령은 optimize로 생성된 모든 캐시 파일과 기본 캐시 드라이버의 모든 키를 삭제합니다.

php artisan optimize:clear

아래 섹션에서는 optimize 명령이 내부적으로 실행하는 개별 최적화 명령들을 각각 설명합니다.

설정 캐시

프로덕션 배포 시 config:cache Artisan 명령을 반드시 실행하세요.

php artisan config:cache

이 명령은 Laravel의 모든 설정 파일을 하나의 캐시 파일로 합칩니다. 설정 값을 불러올 때 파일시스템에 접근하는 횟수가 크게 줄어 성능이 향상됩니다.

WARNING

config:cache 명령을 실행한 이후에는 설정 파일 내에서만 env() 함수를 호출해야 합니다. 설정이 캐시되고 나면 .env 파일은 더 이상 로드되지 않으므로, 설정 파일 외부에서 env()로 .env 변수를 읽으려 하면 항상 null이 반환됩니다.

이벤트 캐시

자동으로 감지된 이벤트와 리스너 매핑도 배포 시점에 캐시해 두어야 합니다. event:cache Artisan 명령으로 처리할 수 있습니다.

php artisan event:cache

라우트 캐시

라우트가 많은 규모 있는 애플리케이션이라면 배포 시 route:cache Artisan 명령을 실행하세요.

php artisan route:cache

이 명령은 모든 라우트 등록 정보를 캐시 파일의 단일 메서드 호출로 압축합니다. 수백 개의 라우트가 등록된 애플리케이션에서 라우트 등록 성능을 눈에 띄게 개선할 수 있습니다.

뷰 캐시

프로덕션 배포 시 view:cache Artisan 명령도 함께 실행하세요.

php artisan view:cache

이 명령은 모든 Blade 뷰를 미리 컴파일해 둡니다. 요청이 들어올 때마다 뷰를 즉시 컴파일하지 않아도 되므로, 뷰를 반환하는 모든 요청의 처리 속도가 향상됩니다.

서비스 재시작

NOTE

Laravel Cloud에 배포하는 경우에는 reload 명령을 별도로 실행할 필요가 없습니다. 모든 서비스의 무중단 재시작이 자동으로 처리됩니다.

새 버전을 배포한 후에는 큐 워커, Laravel Reverb, Laravel Octane과 같이 장시간 실행되는 서비스들을 재시작해야 변경된 코드가 반영됩니다. Laravel은 이러한 서비스들을 종료하는 단일 reload Artisan 명령을 제공합니다.

php artisan reload

Laravel Cloud를 사용하지 않는 경우, 재시작 대상 프로세스가 종료되었을 때 자동으로 다시 실행해 줄 프로세스 모니터(예: Supervisor)를 별도로 설정해야 합니다.

디버그 모드

config/app.php의 debug 옵션은 오류 발생 시 사용자에게 얼마나 많은 정보를 노출할지 결정합니다. 기본적으로 이 옵션은 .env 파일의 APP_DEBUG 환경 변수 값을 따릅니다.

WARNING

프로덕션 환경에서는 이 값이 반드시 false여야 합니다. APP_DEBUG가 true로 설정된 채 프로덕션에 배포되면, 민감한 설정 값들이 최종 사용자에게 노출될 위험이 있습니다.

헬스 라우트

Laravel은 애플리케이션 상태를 모니터링하기 위한 헬스 체크 라우트를 기본으로 제공합니다. 프로덕션 환경에서 이 라우트를 업타임 모니터, 로드 밸런서, 또는 Kubernetes와 같은 오케스트레이션 시스템과 연동해 활용할 수 있습니다.

기본적으로 헬스 체크 라우트는 /up 경로로 제공되며, 애플리케이션이 예외 없이 정상 부팅된 경우 HTTP 200 응답을 반환합니다. 문제가 있다면 HTTP 500 응답이 반환됩니다. bootstrap/app.php 파일에서 이 라우트의 URI를 변경할 수 있습니다.

->withRouting(

    web: __DIR__.'/../routes/web.php',

    commands: __DIR__.'/../routes/console.php',

    health: '/up', //

    health: '/status', //

)

이 라우트로 HTTP 요청이 들어오면, Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트도 함께 발행합니다. 이 이벤트의 리스너를 등록해 데이터베이스나 캐시 상태 등 추가적인 헬스 체크 로직을 구현할 수 있습니다. 문제가 감지되면 리스너에서 예외를 던지기만 하면 됩니다.

Laravel Cloud 또는 Forge로 배포

Laravel Cloud

자동 스케일링을 지원하는 완전 관리형 Laravel 배포 플랫폼을 원한다면 Laravel Cloud를 확인해 보세요. Laravel Cloud는 관리형 컴퓨팅, 데이터베이스, 캐시, 오브젝트 스토리지를 제공하는 강력한 배포 플랫폼입니다.

Laravel 제작팀이 직접 프레임워크와의 완벽한 통합을 위해 최적화했기 때문에, 기존 Laravel 개발 방식 그대로 코드를 작성하면서도 확장 가능한 인프라의 단순함을 경험할 수 있습니다.

Laravel Forge

서버를 직접 관리하고 싶지만 Nginx, MySQL, Redis 등 Laravel 운영에 필요한 다양한 서비스 설정이 부담스럽다면 Laravel Forge를 고려해 보세요. Laravel Forge는 Laravel 애플리케이션을 위한 VPS 서버 관리 플랫폼입니다.

Forge는 DigitalOcean, Linode, AWS 등 다양한 인프라 공급자에서 서버를 생성할 수 있으며, Nginx, MySQL, Redis, Memcached, Beanstalk 등 Laravel 애플리케이션 운영에 필요한 도구들을 자동으로 설치하고 관리해 줍니다.