배포

번역일: 2026년 6월 20일

배포

소개
서버 요구사항
서버 설정
최적화
디버그 모드
헬스 라우트
Forge / Vapor로 간편 배포

소개

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 Forge와 같은 공식 서버 관리 서비스를 활용하는 것을 권장합니다.

아래 설정처럼 모든 요청이 반드시 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 애플리케이션 서버입니다. 아래 명령어 하나로 바로 서빙을 시작할 수 있습니다.

frankenphp php-server -r public/

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

디렉터리 권한

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

최적화

프로덕션 배포 시에는 설정, 이벤트, 라우트, 뷰 등 다양한 파일을 캐싱해 두면 성능을 크게 높일 수 있습니다. Laravel은 이 작업을 한 번에 처리하는 편리한 Artisan 명령어를 제공합니다. 배포 프로세스에 아래 명령어를 포함시키는 것을 권장합니다.

php artisan optimize

캐시를 모두 삭제하고 싶다면 optimize:clear 명령어를 사용하세요. 기본 캐시 드라이버에 저장된 모든 키도 함께 삭제됩니다.

php artisan optimize:clear

아래에서는 optimize 명령어가 내부적으로 실행하는 개별 최적화 명령어들을 하나씩 살펴보겠습니다.

설정 캐싱

배포 과정에서 반드시 아래 명령어를 실행하세요.

php artisan config:cache

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

WARNING

config:cache 명령어를 실행한 이후에는 .env 파일이 더 이상 로드되지 않습니다. 따라서 env() 함수는 반드시 설정 파일(config/*.php) 내부에서만 호출해야 합니다. 설정 캐시가 생성된 뒤 설정 파일 바깥에서 env()를 호출하면 항상 null이 반환됩니다.

이벤트 캐싱

애플리케이션에서 자동 탐색(auto-discovery)으로 등록되는 이벤트-리스너 매핑도 배포 시 캐싱해 두는 것이 좋습니다.

php artisan event:cache

라우트 캐싱

라우트가 많은 대형 애플리케이션이라면 배포 시 라우트 캐싱을 꼭 적용하세요.

php artisan route:cache

이 명령어는 모든 라우트 등록을 단일 메서드 호출로 압축한 캐시 파일을 생성합니다. 라우트 수가 수백 개에 달할 때 특히 부팅 성능 향상 효과가 큽니다.

뷰 캐싱

배포 시 아래 명령어로 Blade 뷰를 미리 컴파일해 두면 요청마다 뷰를 컴파일하는 비용을 없앨 수 있습니다.

php artisan view:cache

디버그 모드

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

WARNING

프로덕션 환경에서 APP_DEBUG 값은 반드시 false여야 합니다. true로 설정되어 있으면 데이터베이스 접속 정보나 API 키 등 민감한 설정 값이 오류 페이지를 통해 외부에 노출될 수 있습니다.

헬스 라우트

Laravel은 애플리케이션 상태를 확인할 수 있는 헬스 체크 라우트를 기본으로 제공합니다. 이 라우트는 업타임 모니터링 서비스, 로드 밸런서, 또는 Kubernetes 같은 오케스트레이션 시스템에서 애플리케이션의 정상 여부를 확인하는 데 활용할 수 있습니다.

기본 엔드포인트는 /up이며, 애플리케이션이 예외 없이 정상 부팅된 경우 HTTP 200을, 그렇지 않으면 HTTP 500을 반환합니다. 엔드포인트 경로는 bootstrap/app.php에서 변경할 수 있습니다.

->withRouting(

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

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

    health: '/up', //

    health: '/status', //

)

이 라우트로 HTTP 요청이 들어오면 Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트를 디스패치합니다. 이 이벤트의 리스너를 등록하면 데이터베이스 연결 상태나 캐시 동작 여부 같은 추가적인 헬스 체크 로직을 구현할 수 있습니다. 문제가 감지되면 리스너 안에서 예외를 던지면 됩니다.

Forge / Vapor로 간편 배포

Laravel Forge

서버 설정을 직접 관리하거나 Nginx, MySQL, Redis 등 여러 서비스를 일일이 구성하기 부담스럽다면 Laravel Forge가 좋은 대안입니다.

Laravel Forge는 DigitalOcean, Linode, AWS 등 다양한 클라우드 인프라 공급자에 서버를 생성하고, Nginx, MySQL, Redis, Memcached, Beanstalk 등 Laravel 운영에 필요한 도구들을 자동으로 설치·관리해 줍니다.

NOTE

Laravel Forge를 이용한 배포 전체 과정이 궁금하다면 Laravel Bootcamp와 Laracasts의 Forge 동영상 시리즈를 참고하세요.

Laravel Vapor

서버 관리 없이 자동 스케일링되는 서버리스 환경에서 Laravel을 운영하고 싶다면 Laravel Vapor를 살펴보세요. Laravel Vapor는 AWS 기반의 서버리스 배포 플랫폼으로, 인프라 관리 부담 없이 확장 가능한 Laravel 운영 환경을 제공합니다. Laravel 개발팀이 직접 프레임워크와의 완벽한 호환성을 보장하도록 설계했기 때문에, 기존 Laravel 개발 방식 그대로 코드를 작성하면서도 서버리스의 이점을 누릴 수 있습니다.