> ## 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 설치와 PHP 환경 세팅 방법을 설명합니다.

## 필요한 환경

Laravel을 시작하기 전에 다음 환경이 필요합니다.

* **PHP 8.3 이상**
* **Composer**(PHP 패키지 매니저)
* **Laravel 인스톨러**(선택 사항이지만 권장)

<Info>
  Node.js/npm 또는 Bun도 프런트엔드 에셋을 컴파일하기 위해 필요합니다.
</Info>

## PHP와 Laravel 인스톨러 설치

PHP와 Composer, Laravel 인스톨러를 한 번에 설치하는 가장 쉬운 방법은 OS에 맞는 다음 명령을 실행하는 것입니다.

<CodeGroup>
  ```shell macOS theme={null}
  /bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
  ```

  ```powershell Windows (관리자 권한으로 실행) theme={null}
  Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))
  ```

  ```shell Linux theme={null}
  /bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
  ```
</CodeGroup>

명령을 실행한 후 터미널 세션을 재시작해 주세요.
PHP와 Composer가 이미 설치되어 있는 경우, Composer를 사용해 Laravel 인스톨러만 설치할 수 있습니다.

```shell theme={null}
composer global require laravel/installer
```

<Tip>
  그래픽 형태의 PHP 관리 도구를 원한다면 [Laravel Herd](#laravel-herd-를-사용한-설치)도 확인해 주세요.
</Tip>

## 새 Laravel 애플리케이션 생성

PHP, Composer, Laravel 인스톨러가 준비되었다면 새 Laravel 애플리케이션을 생성합니다.
인스톨러는 테스트 프레임워크·데이터베이스·스타터 킷 선택을 안내합니다.

```shell theme={null}
laravel new example-app
```

애플리케이션이 생성되면 `dev` Composer 스크립트로 개발 서버를 기동합니다.

```shell theme={null}
cd example-app
npm install && npm run build
composer run dev
```

개발 서버가 기동되면 브라우저에서 [http://localhost:8000](http://localhost:8000)에 접속합니다.

<Info>
  스타터 킷을 사용하면 인증 기능을 포함한 기본 뼈대가 자동 생성됩니다. Laravel 13에서는 React·Vue·Svelte·Livewire 네 종류에서 선택할 수 있습니다.
</Info>

### 스타터 킷 선택지

`laravel new` 명령을 실행하면 다음 스타터 킷 중 하나를 선택할 수 있습니다.

<AccordionGroup>
  <Accordion title="React">
    [Inertia](https://inertiajs.com)를 사용한 React 프런트엔드 스타터 킷입니다. React 19·TypeScript·Tailwind·[shadcn/ui](https://ui.shadcn.com)를 채택하고 있으며, SPA와 서버사이드 라우팅을 조합한 모던한 구성을 제공합니다.
  </Accordion>

  <Accordion title="Vue">
    [Inertia](https://inertiajs.com)를 사용한 Vue 프런트엔드 스타터 킷입니다. Vue Composition API·TypeScript·Tailwind·[shadcn-vue](https://www.shadcn-vue.com/)를 채택하고 있습니다.
  </Accordion>

  <Accordion title="Svelte">
    [Inertia](https://inertiajs.com)를 사용한 Svelte 프런트엔드 스타터 킷입니다. Svelte 5·TypeScript·Tailwind·[shadcn-svelte](https://www.shadcn-svelte.com/)를 채택하고 있습니다.
  </Accordion>

  <Accordion title="Livewire">
    [Laravel Livewire](https://livewire.laravel.com)를 사용한 스타터 킷입니다. PHP만으로 동적인 UI를 구축할 수 있으며, Blade 템플릿을 주로 사용하는 팀에 최적입니다. Tailwind·[Flux UI](https://fluxui.dev)를 채택하고 있습니다.
  </Accordion>
</AccordionGroup>

<Tip>
  어떤 구성을 선택할지 망설여진다면 [프런트엔드](/ko/frontend)에서 Blade·Livewire·Inertia·SPA의 차이를 먼저 정리해 두면 판단이 쉬워집니다.
</Tip>

## Laravel Herd를 사용한 설치

[Laravel Herd](https://herd.laravel.com)는 macOS와 Windows용의 네이티브 Laravel/PHP 개발 환경입니다.
PHP·Nginx·Laravel CLI를 한 번에 설치할 수 있습니다.

### macOS

1. [Herd 웹사이트](https://herd.laravel.com)에서 인스톨러를 다운로드합니다.
2. 인스톨러를 실행하면 PHP가 자동으로 설정됩니다.
3. `~/Herd` 디렉터리가 파크 디렉터리로 설정됩니다.

```shell theme={null}
cd ~/Herd
laravel new my-app
cd my-app
herd open
```

### Windows

1. [Herd 웹사이트](https://herd.laravel.com/windows)에서 Windows 인스톨러를 다운로드합니다.
2. 설치 후 Herd를 기동해 온보딩을 완료합니다.
3. `%USERPROFILE%\Herd`가 파크 디렉터리가 됩니다.

```shell theme={null}
cd ~\Herd
laravel new my-app
cd my-app
herd open
```

## 초기 설정

### 환경 설정

Laravel의 설정 값 다수는 환경에 따라 달라질 수 있습니다.
그래서 애플리케이션 루트에 있는 `.env` 파일에서 중요한 설정 값을 관리합니다.

<Warning>
  `.env` 파일은 소스 컨트롤에 커밋하지 마세요.
  기밀 정보가 유출될 위험이 있습니다.
</Warning>

### 데이터베이스 설정

기본적으로 Laravel은 SQLite를 사용하도록 설정되어 있습니다.
MySQL이나 PostgreSQL을 사용하는 경우에는 `.env` 파일을 갱신해 주세요.

```ini theme={null}
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=
```

SQLite 이외의 데이터베이스를 사용하는 경우에는 마이그레이션을 실행해 테이블을 생성합니다.

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

## IDE 지원

<AccordionGroup>
  <Accordion title="VS Code / Cursor">
    공식 [Laravel VS Code Extension](https://marketplace.visualstudio.com/items?itemName=laravel.vscode-laravel)을 설치하면 문법 강조·스니펫·Artisan 명령 통합·Eloquent 모델의 스마트 자동 완성 등의 Laravel 지원을 사용할 수 있습니다.
  </Accordion>

  <Accordion title="PhpStorm">
    [PhpStorm](https://www.jetbrains.com/phpstorm/laravel/)은 Laravel 프레임워크의 내장 지원을 갖추고 있으며, Blade 템플릿·Eloquent 모델·라우트·뷰·번역의 스마트 자동 완성을 제공합니다.
  </Accordion>
</AccordionGroup>

## 다음 단계

<Card title="디렉터리 구조" icon="folder-open" href="/ko/directory-structure">
  Laravel 프로젝트의 주요 디렉터리와 파일을 이해합니다.
</Card>


## Related topics

- [브로드캐스팅](/ko/broadcasting.md)
- [Laravel Reverb](/ko/reverb.md)
- [Laravel Pint](/ko/pint.md)
- [Laravel Boost](/ko/boost.md)
- [Laravel Prompts](/ko/prompts.md)