설정

업데이트됨

번역일: 2026년 9월 17일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 16일
번역 갱신: 2026년 9월 17일

설정

소개
환경 설정
설정값 접근하기
설정 캐싱
설정 파일 퍼블리싱
디버그 모드
점검 모드

소개

Laravel 프레임워크의 모든 설정 파일은 config 디렉터리에 들어 있습니다. 각 옵션마다 주석으로 설명이 달려있으니, 파일을 하나씩 훑어보면서 어떤 설정 항목들이 있는지 익혀두는 것을 추천합니다.

이 설정 파일들을 통해 데이터베이스 연결 정보, 메일 서버 정보는 물론, 애플리케이션 URL이나 암호화 키 같은 핵심 설정값까지 자유롭게 구성할 수 있습니다.

`about` 명령어

Laravel은 about Artisan 명령어를 통해 애플리케이션의 설정, 드라이버, 환경 정보를 한눈에 보여줄 수 있습니다.

php artisan about

애플리케이션 개요 중 특정 섹션만 확인하고 싶다면 --only 옵션으로 필터링할 수 있습니다.

php artisan about --only=environment

특정 설정 파일의 값을 자세히 살펴보고 싶다면 config:show Artisan 명령어를 사용하세요.

php artisan config:show database

환경 설정

애플리케이션이 실행되는 환경(로컬, 스테이징, 운영 서버 등)에 따라 서로 다른 설정값을 사용해야 하는 경우가 많습니다. 예를 들어 로컬에서는 파일 기반 캐시를, 운영 서버에서는 Redis 캐시를 쓰고 싶을 수 있습니다.

Laravel은 이런 상황을 간편하게 처리할 수 있도록 DotEnv PHP 라이브러리를 사용합니다. Laravel을 새로 설치하면 애플리케이션 루트 디렉터리에 자주 쓰이는 환경 변수들이 정의된 .env.example 파일이 포함되어 있으며, 설치 과정에서 이 파일이 자동으로 .env 파일로 복사됩니다.

Laravel의 기본 .env 파일에는 로컬에서 실행하느냐 운영 서버에서 실행하느냐에 따라 달라질 수 있는 몇 가지 공통 설정값이 들어 있습니다. 이 값들은 config 디렉터리 안의 설정 파일에서 Laravel의 env 함수를 통해 읽어옵니다.

팀 단위로 개발한다면 .env.example 파일을 계속 함께 관리하고 업데이트하는 것이 좋습니다. 예시 설정 파일에 실제 값 대신 자리표시자(placeholder) 값을 넣어두면, 팀원들이 애플리케이션 실행에 어떤 환경 변수가 필요한지 한눈에 파악할 수 있습니다.

NOTE

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

환경 파일 보안

.env 파일은 개발자나 서버마다 서로 다른 환경 설정이 필요할 수 있으므로 소스 관리(Git 등)에 커밋해서는 안 됩니다. 또한 만약 저장소에 침입자가 접근하는 사고가 발생하면 민감한 자격 증명이 그대로 노출된다는 점에서 보안상으로도 위험합니다.

다만 Laravel에 내장된 환경 파일 암호화 기능을 사용하면 환경 파일을 암호화해서 안전하게 소스 관리에 포함시킬 수 있습니다.

추가 환경 파일

환경 변수를 로드하기 전에, Laravel은 APP_ENV 환경 변수가 외부에서 지정되었는지, 또는 --env CLI 인자가 전달되었는지를 먼저 확인합니다. 둘 중 하나가 지정되어 있다면 Laravel은 .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="My Application"

환경 설정값 조회하기

.env 파일에 정의된 모든 변수는 애플리케이션이 요청을 받을 때 PHP의 $_ENV 슈퍼 글로벌에 로드됩니다. 하지만 설정 파일 안에서는 보통 env 함수를 통해 이 값들을 읽어옵니다. 실제로 Laravel의 기본 설정 파일들을 살펴보면 이미 이 함수를 곳곳에서 사용하고 있다는 것을 알 수 있습니다.

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

env 함수의 두 번째 인자는 "기본값"입니다. 해당 키에 대한 환경 변수가 존재하지 않으면 이 기본값이 반환됩니다.

현재 환경 확인하기

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

use Illuminate\Support\Facades\App;

$environment = App::environment();

environment 메서드에 인자를 전달하면 현재 환경이 주어진 값과 일치하는지 확인할 수도 있습니다. 전달된 값 중 하나라도 일치하면 true를 반환합니다.

if (App::environment('local')) {
    // 현재 환경은 local입니다
}

if (App::environment(['local', 'staging'])) {
    // 현재 환경은 local 또는 staging입니다...
}

NOTE

서버 레벨에서 APP_ENV 환경 변수를 정의하면 현재 환경 판별 결과를 덮어쓸 수 있습니다.

환경 파일 암호화

암호화되지 않은 환경 파일은 소스 관리에 절대 포함시켜서는 안 됩니다. 하지만 Laravel은 환경 파일을 암호화하는 기능을 제공하므로, 암호화한 상태로는 다른 애플리케이션 코드와 함께 안전하게 소스 관리에 추가할 수 있습니다.

암호화

환경 파일을 암호화하려면 env:encrypt 명령어를 사용합니다.

php artisan env:encrypt

env:encrypt 명령어를 실행하면 .env 파일을 암호화한 뒤 그 내용을 .env.encrypted 파일에 저장합니다. 복호화 키는 명령어 실행 결과 출력에 표시되며, 반드시 안전한 비밀번호 관리자에 보관해야 합니다. 직접 암호화 키를 지정하고 싶다면 --key 옵션을 사용할 수 있습니다.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

NOTE

지정하는 키의 길이는 사용 중인 암호화 방식(cipher)이 요구하는 길이와 일치해야 합니다. Laravel은 기본적으로 32자 길이의 키가 필요한 AES-256-CBC 방식을 사용합니다. 명령어 실행 시 --cipher 옵션을 전달하면 Laravel의 암호화 도구가 지원하는 다른 방식도 자유롭게 사용할 수 있습니다.

애플리케이션에 .env, .env.staging처럼 여러 개의 환경 파일이 있다면 --env 옵션으로 환경 이름을 지정해서 암호화할 대상 파일을 선택할 수 있습니다.

php artisan env:encrypt --env=staging

읽기 가능한 변수 이름

환경 파일을 암호화할 때 --readable 옵션을 사용하면 변수의 값만 암호화하고 변수 이름은 그대로 남겨둘 수 있습니다.

php artisan env:encrypt --readable

이렇게 하면 다음과 같은 형태의 암호화된 파일이 만들어집니다.

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

이 방식을 쓰면 민감한 값은 노출하지 않으면서도 어떤 환경 변수들이 존재하는지 확인할 수 있습니다. 또한 파일을 복호화하지 않아도 어떤 변수가 추가/삭제/이름 변경되었는지 알 수 있어서 풀 리퀘스트를 검토하기도 훨씬 수월해집니다.

환경 파일을 복호화할 때 Laravel이 어떤 형식으로 암호화되었는지 자동으로 감지하므로, env:decrypt 명령어를 실행할 때 별도 옵션을 추가할 필요는 없습니다.

NOTE

--readable 옵션을 사용하면 원본 환경 파일에 있던 주석과 빈 줄은 암호화 결과물에 포함되지 않습니다.

읽기 가능한 환경 파일 업데이트하기

읽기 가능한 형식으로 암호화된 환경 파일을 업데이트할 때, Laravel은 변경되지 않은 값은 그대로 유지하고 원본 환경 파일에서 더 이상 존재하지 않는 변수는 제거합니다.

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

암호화된 파일이 없다면 새로 생성되며, 기존 파일을 업데이트하는 경우에는 그 파일을 만들 때 사용했던 것과 동일한 암호화 키와 cipher를 지정해야 합니다. 복호화에 실패하면 명령어는 실패하고 기존 파일을 덮어쓰지 않습니다.

모든 값을 처음부터 다시 암호화하고 싶다면 --force 옵션을 사용하세요. 암호화 키를 변경하거나 손상된 암호화 파일을 교체할 때 유용합니다.

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

복호화

환경 파일을 복호화하려면 env:decrypt 명령어를 사용합니다. 이 명령어는 복호화 키가 필요한데, 기본적으로 LARAVEL_ENV_ENCRYPTION_KEY 환경 변수에서 키를 가져옵니다.

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

env:decrypt 명령어를 실행하면 Laravel이 .env.encrypted 파일의 내용을 복호화하여 .env 파일에 기록합니다.

--cipher 옵션을 전달하면 커스텀 암호화 방식을 사용해서 복호화할 수도 있습니다.

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

.env, .env.staging처럼 여러 개의 환경 파일이 있다면 --env 옵션으로 복호화할 대상 환경을 지정할 수 있습니다.

php artisan env:decrypt --env=staging

기존 환경 파일을 덮어쓰려면 env:decrypt 명령어에 --force 옵션을 추가하세요.

php artisan env:decrypt --force

설정값 접근하기

애플리케이션 어디서든 Config 파사드 또는 전역 config 함수를 사용해 설정값을 손쉽게 조회할 수 있습니다. 설정값은 "점(.) 표기법"으로 접근하며, 파일 이름과 옵션 이름을 순서대로 이어서 씁니다. 기본값도 함께 지정할 수 있는데, 해당 설정 옵션이 존재하지 않을 경우 이 기본값이 반환됩니다.

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']);

정적 분석(static analysis)을 돕기 위해 Config 파사드는 타입이 명시된 조회 메서드도 제공합니다. 조회한 설정값이 기대한 타입과 다르면 예외가 발생합니다.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

설정 캐싱

애플리케이션의 속도를 높이려면 config:cache Artisan 명령어를 사용해 모든 설정 파일을 하나의 파일로 캐싱하는 것이 좋습니다. 이 명령어는 애플리케이션의 모든 설정 옵션을 단일 파일로 합쳐주며, 프레임워크가 이 파일을 훨씬 빠르게 불러올 수 있게 해줍니다.

php artisan config:cache 명령어는 보통 운영 환경 배포 과정의 일부로 실행합니다. 로컬 개발 중에는 설정 옵션을 자주 변경해야 하므로 이 명령어를 실행하지 않는 것이 좋습니다.

설정을 캐싱하고 나면, 요청을 처리하거나 Artisan 명령어를 실행할 때 프레임워크는 더 이상 .env 파일을 읽어들이지 않습니다. 따라서 env 함수는 오직 시스템 레벨의 외부 환경 변수만 반환하게 됩니다.

이런 이유로 env 함수는 반드시 애플리케이션의 설정(config) 파일 안에서만 호출해야 합니다. Laravel의 기본 설정 파일들을 보면 이런 사용 예시를 많이 확인할 수 있습니다. 설정값은 앞서 설명한 대로 config 함수를 통해 애플리케이션 어디서든 접근할 수 있습니다.

캐싱된 설정을 삭제하려면 config:clear 명령어를 사용하세요.

php artisan config:clear

WARNING

배포 과정에서 config:cache 명령어를 실행한다면, env 함수를 반드시 설정 파일 안에서만 호출하고 있는지 확인해야 합니다. 설정이 캐싱된 이후에는 .env 파일이 로드되지 않으므로, env 함수는 시스템 레벨의 외부 환경 변수만 반환하게 됩니다.

설정 파일 퍼블리싱

Laravel의 대부분 설정 파일은 이미 애플리케이션의 config 디렉터리에 퍼블리시되어 있습니다. 하지만 cors.php, view.php처럼 대부분의 애플리케이션에서 수정할 일이 거의 없는 일부 설정 파일은 기본적으로 퍼블리시되지 않습니다.

기본적으로 퍼블리시되지 않는 설정 파일이 필요하다면 config:publish Artisan 명령어를 사용하세요.

php artisan config:publishphp artisan config:publish --all

디버그 모드

config/app.php 설정 파일의 debug 옵션은 에러가 발생했을 때 사용자에게 얼마나 많은 정보를 보여줄지 결정합니다. 기본적으로 이 옵션은 .env 파일에 저장된 APP_DEBUG 환경 변수의 값을 따르도록 설정되어 있습니다.

WARNING

로컬 개발 환경에서는 APP_DEBUG 환경 변수를 true로 설정해야 합니다. 하지만 운영 환경에서는 이 값을 항상 false로 설정해야 합니다. 운영 환경에서 이 값이 true로 되어 있으면 민감한 설정 정보가 사용자에게 그대로 노출될 위험이 있습니다.

점검 모드

애플리케이션이 점검 모드(maintenance mode)에 들어가면, 들어오는 모든 요청에 대해 커스텀 뷰가 대신 표시됩니다. 업데이트 작업을 하거나 유지보수를 진행하는 동안 애플리케이션을 손쉽게 "비활성화"할 수 있는 기능입니다. 점검 모드 여부를 확인하는 로직은 애플리케이션의 기본 미들웨어 스택에 이미 포함되어 있습니다. 애플리케이션이 점검 모드 상태라면 상태 코드 503과 함께 Symfony\Component\HttpKernel\Exception\HttpException 인스턴스가 발생합니다.

점검 모드를 활성화하려면 down Artisan 명령어를 실행하세요.

php artisan down

점검 모드 응답에 Refresh HTTP 헤더를 함께 보내고 싶다면 down 명령어를 실행할 때 refresh 옵션을 전달하면 됩니다. Refresh 헤더는 지정된 초 수가 지나면 브라우저가 페이지를 자동으로 새로고침하도록 지시합니다.

php artisan down --refresh=15

down 명령어에 retry 옵션을 전달하면 Retry-After HTTP 헤더 값으로 설정되지만, 대부분의 브라우저는 이 헤더를 실제로 사용하지 않습니다.

php artisan down --retry=60

점검 모드 우회하기

비밀 토큰을 사용해 점검 모드를 우회할 수 있게 하려면, secret 옵션으로 우회용 토큰을 지정하면 됩니다.

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

이 숨겨진 라우트에 접속하면 애플리케이션의 / 라우트로 리다이렉트됩니다. 브라우저에 쿠키가 발급되고 나면, 점검 모드가 아닌 것처럼 애플리케이션을 정상적으로 이용할 수 있습니다.

NOTE

점검 모드 비밀 토큰은 영문자와 숫자, 그리고 필요하다면 대시(-)로만 구성하는 것이 좋습니다. ?나 &처럼 URL에서 특별한 의미를 가지는 문자는 사용하지 않도록 주의하세요.

여러 대의 서버에서 점검 모드 사용하기

기본적으로 Laravel은 파일 기반 방식으로 애플리케이션이 점검 모드인지 판단합니다. 즉, 점검 모드를 활성화하려면 애플리케이션을 서비스하는 서버마다 각각 php artisan down 명령어를 실행해야 합니다.

이 방식이 번거롭다면, Laravel은 캐시 기반으로 점검 모드를 관리하는 방법도 제공합니다. 이 방식을 사용하면 서버 한 대에서만 php artisan down 명령어를 실행하면 됩니다. 이를 사용하려면 애플리케이션의 .env 파일에서 점검 모드 관련 변수를 수정하면 됩니다. 이때 지정하는 캐시 store는 반드시 모든 서버에서 접근 가능해야 합니다. 그래야 모든 서버에서 점검 모드 상태가 일관되게 유지됩니다.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

점검 모드 뷰 사전 렌더링하기

배포 과정에서 php artisan down 명령어를 사용하더라도, Composer 의존성이나 인프라 구성요소가 업데이트되는 도중에 사용자가 애플리케이션에 접근하면 여전히 에러가 발생할 수 있습니다. 이는 애플리케이션이 점검 모드 상태임을 판단하고 템플릿 엔진으로 점검 모드 뷰를 렌더링하기까지, Laravel 프레임워크의 상당 부분이 먼저 부팅되어야 하기 때문입니다.

이런 문제를 피하기 위해 Laravel은 점검 모드 뷰를 미리 렌더링해서, 요청 처리 사이클이 시작되는 가장 이른 시점에 곧바로 반환할 수 있게 해줍니다. 이 뷰는 애플리케이션의 의존성이 로드되기도 전에 렌더링됩니다. down 명령어의 render 옵션을 사용해 원하는 템플릿을 사전 렌더링할 수 있습니다.

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

점검 모드에서 요청 리다이렉트하기

점검 모드 상태에서는 사용자가 어떤 URL로 접근하든 Laravel이 점검 모드 뷰를 보여줍니다. 원한다면 모든 요청을 특정 URL로 리다이렉트하도록 지정할 수도 있는데, 이때는 redirect 옵션을 사용합니다. 예를 들어 모든 요청을 / URI로 리다이렉트하고 싶다면 다음과 같이 실행합니다.

php artisan down --redirect=/

점검 모드 해제하기

점검 모드를 해제하려면 up 명령어를 사용하세요.

php artisan up

NOTE

resources/views/errors/503.blade.php 경로에 직접 뷰 파일을 작성하면 기본 점검 모드 템플릿을 원하는 대로 커스터마이징할 수 있습니다.

점검 모드와 큐

애플리케이션이 점검 모드인 동안에는 큐에 등록된 Job이 처리되지 않습니다. 애플리케이션이 점검 모드에서 벗어나면 Job은 다시 정상적으로 처리됩니다.

점검 모드의 대안

점검 모드를 사용하려면 애플리케이션이 몇 초 동안은 다운타임을 겪을 수밖에 없습니다. 만약 무중단 배포(zero-downtime deployment)를 원한다면 Laravel Cloud와 같은 완전 관리형 플랫폼에서 애플리케이션을 운영하는 것도 좋은 대안입니다.