설정

번역일: 2026년 6월 20일

설정

소개
환경 설정
설정 값 접근
설정 캐싱
디버그 모드
점검 모드

소개

Laravel 프레임워크의 모든 설정 파일은 config 디렉터리에 있습니다. 각 옵션에는 설명이 함께 포함되어 있으므로, 파일을 직접 열어보며 어떤 옵션이 있는지 살펴보는 것을 권장합니다.

설정 파일에서는 데이터베이스 연결 정보, 메일 서버 정보, 그리고 애플리케이션의 타임존·암호화 키 같은 핵심 값들을 관리합니다.

애플리케이션 개요 확인

about Artisan 명령어를 실행하면 현재 애플리케이션의 설정, 드라이버, 환경 정보를 한눈에 확인할 수 있습니다.

php artisan about

특정 섹션만 확인하고 싶다면 --only 옵션을 사용하세요.

php artisan about --only=environment

특정 설정 파일의 값을 상세히 확인하려면 config:show 명령어를 사용합니다.

php artisan config:show database

환경 설정

로컬 개발 환경과 운영 서버는 보통 서로 다른 설정 값이 필요합니다. 예를 들어, 캐시 드라이버를 로컬에서는 array로, 운영 환경에서는 redis로 다르게 쓸 수 있습니다.

Laravel은 이를 쉽게 처리하기 위해 DotEnv PHP 라이브러리를 사용합니다. 새로 생성된 Laravel 프로젝트의 루트 디렉터리에는 .env.example 파일이 있으며, 설치 과정에서 자동으로 .env 파일로 복사됩니다.

.env 파일에는 로컬과 운영 환경에 따라 달라질 수 있는 공통 설정 값들이 정의되어 있습니다. 이 값들은 config 디렉터리 안의 설정 파일에서 env() 함수를 통해 읽어옵니다.

팀 단위로 개발할 때는 .env.example 파일을 함께 관리하는 것이 좋습니다. 예시 파일에 플레이스홀더 값을 넣어두면, 새로 합류한 팀원이 어떤 환경 변수가 필요한지 바로 파악할 수 있습니다.

NOTE

.env 파일의 변수는 서버 레벨이나 시스템 레벨에서 정의된 환경 변수로 덮어쓸 수 있습니다.

환경 파일 보안

.env 파일에는 데이터베이스 비밀번호, API 키 등 민감한 정보가 담겨 있습니다. 개발자나 서버마다 설정이 다를 수 있기도 하므로, .env 파일은 절대로 Git 등의 소스 컨트롤에 커밋하지 않아야 합니다. 만약 저장소에 접근 권한이 없는 누군가에게 노출된다면 보안 사고로 이어질 수 있습니다.

단, Laravel의 환경 파일 암호화 기능을 사용하면 암호화된 환경 파일은 소스 컨트롤에 안전하게 포함할 수 있습니다.

추가 환경 파일

환경 변수를 불러오기 전에, Laravel은 외부에서 APP_ENV 환경 변수가 지정되었는지 또는 CLI에서 --env 인수가 전달되었는지 확인합니다. 해당하는 경우, .env.[APP_ENV] 파일이 있으면 그 파일을 읽고, 없으면 기본 .env 파일을 사용합니다.

환경 변수 타입

.env 파일의 값은 기본적으로 문자열로 파싱됩니다. 다만 env() 함수가 더 다양한 타입을 반환할 수 있도록 몇 가지 예약 값이 지원됩니다.

`.env` 값	`env()` 반환값
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

값에 공백이 포함되어야 한다면 큰따옴표로 감싸서 정의합니다.

APP_NAME="내 애플리케이션"

환경 설정 값 읽기

애플리케이션이 요청을 받으면 .env 파일의 변수들이 PHP의 $_ENV 슈퍼글로벌에 자동으로 로드됩니다. 설정 파일에서는 env() 함수로 이 값들을 읽어올 수 있습니다. Laravel의 기본 설정 파일을 살펴보면 이미 이 패턴이 곳곳에 사용되고 있습니다.

'debug' => env('APP_DEBUG', false),

env() 함수의 두 번째 인수는 기본값입니다. 해당 환경 변수가 정의되어 있지 않을 때 이 값이 반환됩니다.

현재 환경 확인

현재 애플리케이션 환경은 .env 파일의 APP_ENV 변수로 결정됩니다. App 파사드의 environment 메서드로 이 값을 확인할 수 있습니다.

use Illuminate\Support\Facades\App;

$environment = App::environment();

environment 메서드에 인수를 전달하면, 현재 환경이 해당 값과 일치하는지 검사합니다. 전달된 값 중 하나라도 일치하면 true를 반환합니다.

if (App::environment('local')) {
    // 로컬 환경입니다
}

if (App::environment(['local', 'staging'])) {
    // 로컬 또는 스테이징 환경입니다
}

NOTE

서버 레벨에서 APP_ENV 환경 변수를 직접 정의하면, .env 파일의 값보다 우선 적용됩니다.

환경 파일 암호화

암호화되지 않은 환경 파일은 소스 컨트롤에 포함해서는 안 됩니다. 하지만 Laravel의 환경 파일 암호화 기능을 사용하면 암호화된 파일을 안전하게 저장소에 포함할 수 있습니다.

암호화

env:encrypt 명령어로 환경 파일을 암호화합니다.

php artisan env:encrypt

이 명령어를 실행하면 .env 파일이 암호화되어 .env.encrypted 파일로 저장됩니다. 복호화 키는 명령어 실행 결과에 출력되며, 안전한 비밀번호 관리 도구에 보관해야 합니다. 직접 키를 지정하려면 --key 옵션을 사용합니다.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

NOTE

제공하는 키의 길이는 사용하는 암호화 알고리즘이 요구하는 길이와 일치해야 합니다. 기본 알고리즘인 AES-256-CBC는 32자 키가 필요합니다. --cipher 옵션으로 Laravel 암호화 모듈이 지원하는 다른 알고리즘을 사용할 수도 있습니다.

.env와 .env.staging처럼 여러 환경 파일이 있다면 --env 옵션으로 대상 파일을 지정합니다.

php artisan env:encrypt --env=staging

복호화

env:decrypt 명령어로 암호화된 환경 파일을 복호화합니다. 복호화 키는 LARAVEL_ENV_ENCRYPTION_KEY 환경 변수에서 읽어옵니다.

php artisan env:decrypt

--key 옵션으로 키를 직접 전달할 수도 있습니다.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

명령어를 실행하면 .env.encrypted 파일의 내용이 복호화되어 .env 파일로 저장됩니다.

커스텀 암호화 알고리즘을 사용했다면 --cipher 옵션을 함께 지정합니다.

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

여러 환경 파일이 있는 경우 --env 옵션으로 대상을 지정합니다.

php artisan env:decrypt --env=staging

이미 존재하는 환경 파일을 덮어쓰려면 --force 옵션을 추가합니다.

php artisan env:decrypt --force

설정 값 접근

애플리케이션 어디에서든 Config 파사드 또는 전역 config() 함수를 사용해 설정 값에 접근할 수 있습니다. 설정 값은 파일명.옵션명 형태의 점(dot) 문법으로 참조하며, 해당 값이 없을 때 반환할 기본값도 지정할 수 있습니다.

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

// 설정 값이 없을 경우 기본값 반환
$value = config('app.timezone', 'Asia/Seoul');

런타임에 설정 값을 변경하려면 Config 파사드의 set 메서드를 호출하거나 config() 함수에 배열을 전달합니다.

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

설정 캐싱

config:cache Artisan 명령어를 실행하면 모든 설정 파일이 하나의 파일로 합쳐져 캐시됩니다. 프레임워크가 이 파일을 한 번에 읽어오므로 애플리케이션 응답 속도가 빨라집니다.

php artisan config:cache

이 명령어는 일반적으로 운영 환경 배포 과정에서 실행합니다. 로컬 개발 중에는 설정을 자주 변경하게 되므로 캐싱하지 않는 것이 좋습니다.

설정이 캐싱된 이후에는 요청 처리나 Artisan 명령어 실행 시 .env 파일을 더 이상 읽지 않습니다. 따라서 env() 함수는 반드시 config 디렉터리의 설정 파일 안에서만 호출해야 합니다. 캐싱 이후 설정 파일 외부에서 env()를 호출하면 시스템 환경 변수 외에는 값을 가져올 수 없습니다.

캐시된 설정을 삭제하려면 다음 명령어를 사용합니다.

php artisan config:clear

WARNING

배포 과정에서 config:cache를 실행한다면, 설정 파일 내부에서만 env() 함수를 호출하고 있는지 반드시 확인하세요. 캐싱 후에는 .env 파일이 로드되지 않으므로, 설정 파일 외부에서 env()를 호출하면 시스템 레벨 환경 변수만 반환됩니다.

디버그 모드

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

WARNING

로컬 개발 환경에서는 APP_DEBUG를 true로 설정하세요. 운영 환경에서는 반드시 false로 설정해야 합니다. 운영 환경에서 true로 설정하면 민감한 설정 정보가 최종 사용자에게 노출될 위험이 있습니다.

점검 모드

점검 모드(Maintenance Mode)를 활성화하면 모든 요청에 대해 지정된 점검 화면이 표시됩니다. 배포 작업이나 유지보수 중에 애플리케이션을 일시적으로 비활성화할 때 유용합니다. 점검 모드 여부는 기본 미들웨어 스택에서 자동으로 확인하며, 점검 모드일 때는 HTTP 상태 코드 503과 함께 Symfony\Component\HttpKernel\Exception\HttpException이 발생합니다.

점검 모드를 활성화하려면 down 명령어를 실행합니다.

php artisan down

점검 모드 응답에 Refresh HTTP 헤더를 포함하려면 --refresh 옵션을 사용합니다. 브라우저가 지정된 초 후 자동으로 페이지를 새로고침합니다.

php artisan down --refresh=15

--retry 옵션을 사용하면 Retry-After HTTP 헤더 값이 설정됩니다. 브라우저는 대부분 이 헤더를 무시하지만, 일부 클라이언트에서는 유용할 수 있습니다.

php artisan down --retry=60

점검 모드 우회

특정 사용자(예: 개발자)가 점검 모드 중에도 애플리케이션에 접근할 수 있도록 시크릿 토큰을 설정할 수 있습니다.

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

점검 모드 활성화 후 해당 토큰이 포함된 URL로 접근하면, Laravel이 브라우저에 우회 쿠키를 발급합니다.

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Laravel이 시크릿 토큰을 자동으로 생성하게 하려면 --with-secret 옵션을 사용합니다. 점검 모드 진입 후 생성된 시크릿이 화면에 출력됩니다.

php artisan down --with-secret

해당 URL로 접근하면 애플리케이션 루트(/)로 리다이렉트됩니다. 이후 브라우저에 쿠키가 발급되어, 점검 모드 중에도 정상적으로 애플리케이션을 이용할 수 있습니다.

NOTE

점검 모드 시크릿은 영문자·숫자·하이픈으로 구성하는 것이 좋습니다. URL에서 특수한 의미를 가지는 ?, & 같은 문자는 사용하지 않도록 주의하세요.

점검 화면 사전 렌더링

배포 중 php artisan down을 실행한 직후, Composer 의존성 업데이트 등이 진행되는 동안 사용자가 접속하면 오류 화면이 표시될 수 있습니다. Laravel 프레임워크의 상당 부분이 부트되어야 점검 모드를 인식하고 화면을 렌더링할 수 있기 때문입니다.

이를 방지하기 위해, Laravel은 요청 사이클의 가장 초기 단계에서 반환할 점검 화면을 미리 렌더링하는 기능을 제공합니다. --render 옵션으로 사전 렌더링할 템플릿을 지정할 수 있습니다.

php artisan down --render="errors::503"

점검 모드 요청 리다이렉트

점검 모드 중 모든 요청을 특정 URL로 리다이렉트하려면 --redirect 옵션을 사용합니다. 예를 들어, 모든 요청을 루트(/)로 보내려면 다음과 같이 실행합니다.

php artisan down --redirect=/

점검 모드 해제

점검 모드를 해제하려면 up 명령어를 실행합니다.

php artisan up

NOTE

resources/views/errors/503.blade.php 파일을 직접 만들면 기본 점검 화면 템플릿을 커스터마이징할 수 있습니다.

점검 모드와 큐

점검 모드가 활성화된 동안에는 큐 Job이 처리되지 않습니다. 점검 모드가 해제되면 대기 중이던 Job들이 정상적으로 처리됩니다.

점검 모드 대안

점검 모드는 활성화되는 동안 수 초간의 다운타임이 발생합니다. 무중단 배포가 필요하다면 Laravel Vapor나 Envoyer 같은 서비스를 고려해 보세요.