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

# WSL로 PHP와 Composer와 Node.js 설치하기 (Windows)

> Windows 10/11에서 WSL 2를 사용해 PHP · Composer · Node.js를 설치하고, Laravel 개발 환경을 갖추는 단계별 가이드입니다.

## 시작하며

Windows에서 Laravel을 개발하려면 \*\*WSL(Windows Subsystem for Linux)\*\*을 사용하는 것이 베스트 프랙티스입니다. Linux의 툴 체인을 그대로 사용할 수 있으므로, macOS나 프로덕션 서버와 같은 명령이 통합니다.

이 가이드에서는 WSL 2 상의 Ubuntu에서 PHP · Composer · Node.js (nvm 경유)를 설치하고, `laravel new`가 동작하는 상태로 만들기까지를 설명합니다.

<Info>
  대상 환경: Windows 10 (버전 2004 이후) 또는 Windows 11. WSL 2를 사용합니다.
</Info>

***

## WSL 설치

<Steps>
  <Step title="PowerShell을 관리자로 열기">
    시작 메뉴에서 "PowerShell"을 검색하고 "관리자로 실행"을 선택합니다.
  </Step>

  <Step title="WSL과 Ubuntu 설치">
    ```powershell theme={null}
    wsl --install
    ```

    이 명령으로 WSL 2와 Ubuntu(기본 배포판)가 설치됩니다. 완료 후 PC를 재기동합니다.
  </Step>

  <Step title="Ubuntu 셋업">
    재기동 후 Ubuntu가 자동으로 기동합니다. 사용자 이름과 패스워드를 설정하세요. 이 패스워드는 `sudo` 명령에서 사용합니다.

    <Warning>
      패스워드는 입력 중에 화면에 표시되지 않습니다. 정확히 입력해 주세요.
    </Warning>
  </Step>

  <Step title="패키지 리스트 갱신">
    Ubuntu 터미널에서 이하를 실행합니다.

    ```bash theme={null}
    sudo apt update && sudo apt upgrade -y
    ```
  </Step>
</Steps>

***

## PHP 설치

Ubuntu의 표준 리포지토리의 PHP에는 오래된 버전이 포함되어 있는 경우가 있습니다. `ondrej/php` PPA를 사용하여 최신 버전을 설치합니다.

<Steps>
  <Step title="필요한 패키지 설치">
    ```bash theme={null}
    sudo apt install -y software-properties-common
    ```
  </Step>

  <Step title="ondrej/php PPA 추가">
    ```bash theme={null}
    sudo add-apt-repository ppa:ondrej/php
    sudo apt update
    ```
  </Step>

  <Step title="PHP 8.3과 필요한 확장 설치">
    Laravel 13은 PHP 8.3 이상이 필요합니다.

    ```bash theme={null}
    sudo apt install -y php8.3 php8.3-cli php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-sqlite3 php8.3-mysql
    ```
  </Step>

  <Step title="버전 확인">
    ```bash theme={null}
    php --version
    ```

    `PHP 8.3.x` 이상이 표시되면 성공입니다.
  </Step>

  <Step title="(선택) 여러 버전 전환">
    여러 PHP 버전이 필요한 경우는 `update-alternatives`로 전환할 수 있습니다.

    ```bash theme={null}
    sudo update-alternatives --config php
    ```

    설치된 버전 일람이 표시되므로, 사용할 버전의 번호를 입력합니다.
  </Step>
</Steps>

***

## Composer 설치

Composer는 공식 인스톨러를 사용하여 설치합니다.

<Steps>
  <Step title="필요한 패키지 확인">
    ```bash theme={null}
    sudo apt install -y curl php8.3-cli unzip
    ```
  </Step>

  <Step title="공식 인스톨러 다운로드 및 실행">
    ```bash theme={null}
    curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
    sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
    ```
  </Step>

  <Step title="버전 확인">
    ```bash theme={null}
    composer --version
    ```
  </Step>

  <Step title="글로벌 설치 경로 설정">
    `composer global require`로 설치한 패키지(Laravel 인스톨러 등)를 사용할 수 있도록, `~/.composer/vendor/bin`을 `PATH`에 추가합니다.

    `~/.bashrc`(또는 `~/.zshrc`)에 이하를 추기합니다.

    ```bash theme={null}
    export PATH="$HOME/.composer/vendor/bin:$PATH"
    ```

    설정을 반영합니다.

    ```bash theme={null}
    source ~/.bashrc
    ```
  </Step>
</Steps>

***

## nvm 설치

Node.js는 nvm(Node Version Manager)을 사용하여 사용자 단위로 설치합니다. `sudo` 없이 관리할 수 있으므로, 글로벌 npm 패키지를 사용하는 AI 도구나 CLI와의 궁합이 좋습니다.

<Steps>
  <Step title="nvm 설치">
    최신 설치 스크립트는 [nvm의 GitHub 리포지토리](https://github.com/nvm-sh/nvm)에서 확인할 수 있습니다.

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    ```
  </Step>

  <Step title="셸 설정 파일에 추기">
    설치 스크립트는 자동으로 `~/.bashrc`에 이하를 추기합니다. 추기되지 않은 경우는 수동으로 추가해 주세요.

    ```bash theme={null}
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
    ```

    설정을 반영합니다.

    ```bash theme={null}
    source ~/.bashrc
    ```

    zsh를 사용하고 있는 경우는 `~/.zshrc`에 마찬가지로 추기하고, `source ~/.zshrc`로 반영합니다.
  </Step>

  <Step title="설치 확인">
    ```bash theme={null}
    nvm --version
    ```
  </Step>
</Steps>

***

## Node.js 설치

<Steps>
  <Step title="LTS 버전 설치">
    ```bash theme={null}
    nvm install --lts
    ```
  </Step>

  <Step title="기본으로 설정">
    새 터미널 세션에서도 자동으로 사용되도록 기본 버전을 설정합니다.

    ```bash theme={null}
    nvm alias default node
    ```
  </Step>

  <Step title="버전 확인">
    ```bash theme={null}
    node --version
    npm --version
    ```
  </Step>
</Steps>

***

## Laravel 설치 확인

<Steps>
  <Step title="Laravel 인스톨러 도입">
    ```bash theme={null}
    composer global require laravel/installer
    ```
  </Step>

  <Step title="새 프로젝트 생성">
    ```bash theme={null}
    laravel new my-app
    ```

    대화식 셋업이 시작됩니다. 스타터 킷이나 인증의 유무 등을 선택할 수 있습니다.
  </Step>

  <Step title="개발 서버 기동">
    ```bash theme={null}
    cd my-app
    php artisan serve
    ```

    브라우저에서 `http://localhost:8000`에 접속하여, Laravel의 웰컴 페이지가 표시되면 완료입니다.

    <Tip>
      WSL에서 Windows의 브라우저로 `localhost`에 접근할 수 없는 경우에는, `php artisan serve --host=0.0.0.0`으로 기동해 보세요.
    </Tip>
  </Step>
</Steps>

***

## 보충: 개발 효율을 올리는 도구

### Windows Terminal

Windows Terminal을 사용하면, 여러 탭에서 WSL · PowerShell · 명령 프롬프트를 일원 관리할 수 있습니다. Microsoft Store에서 무료로 설치할 수 있습니다.

* 탭에서 여러 셸을 병렬 조작
* Ubuntu 셸을 기본으로 설정 가능
* 폰트나 색 배합을 자유롭게 커스터마이즈

### VS Code Remote - WSL 확장

VS Code의 [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) 확장을 사용하면, WSL 내의 파일을 Windows의 VS Code에서 직접 편집할 수 있습니다.

```bash theme={null}
# WSL 터미널에서 프로젝트를 VS Code로 열기
code .
```

첫 실행 시에 VS Code 서버가 WSL 내에 자동 설치됩니다. 이후에는 네이티브와 동등한 조작감으로 개발할 수 있습니다.


## Related topics

- [Homebrew로 PHP와 Composer와 Node.js 설치하기 (macOS)](/ko/blog/mac-setup.md)
- [설치](/ko/installation.md)
- [Orchestra Testbench로 Laravel 패키지를 테스트하기](/ko/advanced/package-testing.md)
- [Laravel이란](/ko/introduction.md)
- [MongoDB](/ko/mongodb.md)