> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 설정

> Laravel의 설정 파일, 환경 변수(.env), 설정 값 접근 방법, 캐시, 디버그 모드, 유지 보수 모드를 설명합니다.

## 소개

Laravel 프레임워크의 설정 파일은 모두 `config/` 디렉터리에 저장되어 있습니다. 각 옵션에는 코멘트가 붙어 있으므로 파일을 열고 이용 가능한 옵션을 확인해 봐 주세요.

설정 파일에서는 데이터베이스 접속 정보·메일 서버 정보·애플리케이션 URL이나 암호화 키 등 다양한 코어 설정 값을 관리합니다.

```mermaid theme={null}
flowchart LR
    A[".env 파일"] -->|env()| B["config/ 파일"]
    B -->|config()| C["애플리케이션"]
```

### `about` 명령

`about` Artisan 명령을 사용하면 애플리케이션의 설정·드라이버·환경의 개요를 확인할 수 있습니다.

```shell theme={null}
php artisan about
```

특정 섹션만 확인하고 싶은 경우에는 `--only` 옵션을 사용합니다.

```shell theme={null}
php artisan about --only=environment
```

특정 설정 파일의 값을 자세히 확인하려면 `config:show` 명령이 편리합니다.

```shell theme={null}
php artisan config:show database
```

## 환경 설정(.env)

실행 환경에 따라 설정 값을 전환하고 싶은 경우가 많이 있습니다. 예를 들어 로컬과 프로덕션에서 캐시 드라이버를 바꾸고 싶은 경우 등입니다.

Laravel은 이를 간단하게 하기 위해 [DotEnv](https://github.com/vlucas/phpdotenv) PHP 라이브러리를 이용하고 있습니다. 새로 설치할 때 애플리케이션의 루트 디렉터리에는 일반적인 환경 변수가 정의된 `.env.example` 파일이 포함되어 있으며, 설치 과정 중에 자동으로 `.env`로 복사됩니다.

<Info>
  팀에서 개발하는 경우, `.env.example` 파일을 갱신하면서 리포지토리에 포함해 두면 편리합니다. 플레이스홀더 값을 설정해 두면 팀의 다른 개발자가 어떤 환경 변수가 필요한지 명확히 파악할 수 있습니다.
</Info>

### 환경 파일의 보안

<Warning>
  `.env` 파일은 소스 컨트롤에 커밋하지 마세요. 개발자나 서버별로 다른 설정이 필요하며, 리포지토리에 포함하면 사고 발생 시 기밀 정보가 유출될 위험이 있습니다.
</Warning>

다만 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`  |

공백을 포함하는 값을 설정하려면 큰따옴표로 감쌉니다.

```ini theme={null}
APP_NAME="My Application"
```

### 환경 변수 취득

`.env` 파일에 작성한 모든 변수는 요청을 받을 때 `$_ENV` PHP 슈퍼글로벌에 로드됩니다. 설정 파일 내에서는 `env()` 함수를 사용해 값을 가져올 수 있습니다.

```php theme={null}
'debug' => (bool) env('APP_DEBUG', false),
```

두 번째 인수는 기본값입니다. 해당 환경 변수가 존재하지 않는 경우에 반환됩니다.

### 현재 환경 확인

현재 환경은 `.env` 파일의 `APP_ENV` 변수로 결정됩니다. `App` 파사드의 `environment` 메서드로 가져올 수 있습니다.

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

인수를 전달해 특정 환경인지 확인할 수도 있습니다.

```php theme={null}
if (App::environment('local')) {
    // 로컬 환경
}

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

### 환경 파일의 암호화

암호화되지 않은 환경 파일은 소스 컨트롤에 저장해서는 안 되지만, Laravel에는 환경 파일을 암호화하는 기능이 있습니다.

```shell theme={null}
php artisan env:encrypt
```

실행하면 `.env`가 암호화되고, 암호화된 내용이 `.env.encrypted` 파일에 저장됩니다. 복호화 키는 명령의 출력에 표시되므로 안전한 비밀번호 매니저에 저장해 주세요.

복호화하려면 `env:decrypt` 명령을 사용합니다.

```shell theme={null}
php artisan env:decrypt
```

## 설정 값 접근

`Config` 파사드나 글로벌 `config()` 함수를 사용해 애플리케이션 어디에서든 설정 값에 접근할 수 있습니다. "점 표기법"을 사용해 파일명과 옵션명을 조합해 지정합니다.

```php theme={null}
use Illuminate\Support\Facades\Config;

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

// 글로벌 함수로도 가져올 수 있다
$value = config('app.timezone');

// 존재하지 않을 경우의 기본값을 지정
$value = config('app.timezone', 'Asia/Tokyo');
```

실행 시 설정 값을 변경하려면 `Config::set()` 또는 배열을 `config()`에 전달합니다.

```php theme={null}
Config::set('app.timezone', 'America/Chicago');

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

타입 지정 취득 메서드도 준비되어 있으며, 타입이 일치하지 않는 경우 예외가 던져집니다.

```php theme={null}
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');
```

## 설정 캐시

애플리케이션의 성능을 향상시키려면 모든 설정 파일을 하나의 파일로 캐시합니다.

```shell theme={null}
php artisan config:cache
```

이 명령은 모든 설정 옵션을 하나의 파일로 모아 프레임워크가 빠르게 로드할 수 있게 합니다.

<Warning>
  `config:cache` 명령은 프로덕션 환경의 배포 프로세스 일부로 실행해 주세요. 로컬 개발 중에는 설정이 자주 바뀌므로 실행하지 않는 것을 권장합니다.
</Warning>

캐시가 만들어지면 `.env` 파일은 프레임워크의 요청이나 Artisan 명령 실행 시에 로드되지 않게 됩니다. 따라서 `env()` 함수는 시스템 레벨의 환경 변수만 반환합니다.

<Tip>
  이 때문에 `env()` 함수는 반드시 `config/` 디렉터리 내의 설정 파일에서만 호출해 주세요. 애플리케이션 내의 다른 곳에서는 `config()` 함수를 사용해 설정 값을 가져옵니다.
</Tip>

캐시를 삭제하려면 `config:clear` 명령을 사용합니다.

```shell theme={null}
php artisan config:clear
```

### 설정 파일 게시

Laravel의 설정 파일 다수는 이미 `config/` 디렉터리에 게시되어 있지만, `cors.php`나 `view.php` 등 일부 파일은 기본적으로 게시되어 있지 않습니다.

미게시된 설정 파일을 게시하려면 `config:publish` 명령을 사용합니다.

```shell theme={null}
php artisan config:publish

php artisan config:publish --all
```

## 디버그 모드

`config/app.php`의 `debug` 옵션은 오류 정보를 사용자에게 어느 정도 표시할지를 결정합니다. 이 옵션은 기본적으로 `.env` 파일의 `APP_DEBUG` 환경 변수 값을 따릅니다.

<Warning>
  **프로덕션 환경에서는 `APP_DEBUG`를 반드시 `false`로 설정해 주세요.** `true` 그대로 두면 애플리케이션의 기밀 설정 값이 최종 사용자에게 공개될 위험이 있습니다.
</Warning>

```ini theme={null}
# 로컬 개발
APP_DEBUG=true

# 프로덕션 환경
APP_DEBUG=false
```

## 유지 보수 모드

애플리케이션이 유지 보수 모드일 때 모든 요청에 대해 커스텀 뷰가 표시됩니다. 이를 통해 업데이트 중이나 유지 보수 작업 중에 애플리케이션을 일시적으로 "무효화"할 수 있습니다.

### 유지 보수 모드 활성화

```shell theme={null}
php artisan down
```

`--refresh` 옵션을 지정하면 브라우저가 지정한 초 수 후에 자동으로 다시 로드됩니다.

```shell theme={null}
php artisan down --refresh=15
```

`--retry` 옵션은 `Retry-After` HTTP 헤더의 값으로 설정됩니다.

```shell theme={null}
php artisan down --retry=60
```

### 유지 보수 모드 바이패스

시크릿 토큰을 사용해 특정 사용자만 접근할 수 있도록 하려면 `--secret` 옵션을 사용합니다.

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

`--with-secret` 옵션을 사용하면 Laravel이 토큰을 자동 생성합니다.

```shell theme={null}
php artisan down --with-secret
```

### 여러 서버에서의 유지 보수 모드

기본적으로 Laravel은 파일 기반으로 유지 보수 모드를 관리합니다. 여러 서버 구성인 경우에는 캐시 기반 방법이 편리합니다.

```ini theme={null}
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
```

### 유지 보수 뷰의 사전 렌더링

배포 중에 `php artisan down`을 실행하는 경우, 의존 관계 갱신 중에 접근한 사용자가 오류를 보게 될 수 있습니다. 이를 방지하려면 `--render` 옵션으로 뷰를 사전 렌더링합니다.

```shell theme={null}
php artisan down --render="errors::503"
```

유지 보수 모드 중에 모든 요청을 특정 URL로 리다이렉트할 수도 있습니다.

```shell theme={null}
php artisan down --redirect=/
```

### 유지 보수 모드 무효화

```shell theme={null}
php artisan up
```

<Info>
  유지 보수 모드의 기본 템플릿은 `resources/views/errors/503.blade.php`를 생성함으로써 커스터마이징할 수 있습니다.
</Info>

<Tip>
  다운타임을 완전히 없애고 싶은 경우, [Laravel Cloud](https://cloud.laravel.com) 같은 풀 매니지드 플랫폼의 이용을 검토해 주세요.
</Tip>

## 다음 단계

<Card title="라우팅" icon="route" href="/ko/routing">
  URL과 컨트롤러를 연결하는 라우팅의 기초를 배웁니다.
</Card>


## Related topics

- [비밀번호 재설정](/ko/passwords.md)
- [데이터베이스 설정](/ko/database.md)
- [WebSocket (Jetstream / Firehose)](/ko/packages/laravel-bluesky/websocket.md)
- [해시(Hashing)](/ko/hashing.md)
- [Labeler](/ko/packages/laravel-bluesky/labeler.md)