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

# Homebrew로 PHP와 Composer와 Node.js 설치하기 (macOS)

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

## 시작하며

Laravel 팀은 초보자용으로 [Herd](https://herd.laravel.com/)나 `php.new`를 준비하고 있지만, 시니어 엔지니어는 패키지 매니저로 각 도구를 개별 관리하는 것을 선호합니다. 스스로 버전을 제어할 수 있고, 여러 프로젝트에서 다른 PHP 버전을 전환하는 것도 간단합니다.

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

<Info>
  대상 환경: macOS 13 Ventura 이후. Apple Silicon (M1/M2/M3) · Intel 어느 쪽에서든 대응합니다.
</Info>

***

## Homebrew 설치

Homebrew는 macOS용 패키지 매니저입니다. 아직 설치하지 않은 경우, 터미널에서 다음을 실행합니다.

```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

설치 후, Apple Silicon의 경우 셸 설정 파일(`~/.zprofile` 등)에 다음 행이 자동 추가됩니다. 수동으로 추가한 경우에는 설정을 다시 로드해 주세요.

```bash theme={null}
eval "$(/opt/homebrew/bin/brew shellenv)"
```

설치를 확인합니다.

```bash theme={null}
brew --version
```

***

## PHP 설치

<Steps>
  <Step title="최신 PHP 설치">
    Homebrew의 `php` 포뮬라는 항상 최신 안정 버전을 가리키고 있습니다. Laravel 13은 PHP 8.3 이상이 필요합니다.

    ```bash theme={null}
    brew install php
    ```
  </Step>

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

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

  <Step title="(선택) 특정 버전 사용">
    여러 PHP 버전을 관리하고 싶은 경우는, 버전이 붙은 포뮬라를 설치합니다.

    ```bash theme={null}
    brew install php@8.3
    ```

    버전을 전환하려면 `brew link`를 사용합니다.

    ```bash theme={null}
    brew unlink php
    brew link php@8.3 --force --overwrite
    ```

    현재 링크된 버전을 확인합니다.

    ```bash theme={null}
    php --version
    ```
  </Step>
</Steps>

***

## Composer 설치

<Steps>
  <Step title="Composer 설치">
    Homebrew에서 직접 설치할 수 있습니다.

    ```bash theme={null}
    brew install composer
    ```
  </Step>

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

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

    `~/.zshrc`(또는 `~/.bashrc`)에 다음을 추기합니다.

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

    설정을 반영합니다.

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

***

## nvm 설치

Node.js는 nvm(Node Version Manager)을 사용하여 사용자 단위로 설치합니다. `root` 권한 없이 관리할 수 있으므로, 글로벌 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="셸 설정 파일에 추기">
    설치 스크립트는 자동으로 `~/.zshrc`(또는 `~/.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 ~/.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의 웰컴 페이지가 표시되면 완료입니다.
  </Step>
</Steps>

***

## Herd와의 사용 구분

|               | Homebrew 수동 구축              | Herd                     |
| ------------- | --------------------------- | ------------------------ |
| **대상자**       | 버전 관리나 설정을 세밀하게 제어하고 싶은 개발자 | 빠르게 시작하고 싶은 초보자 · 개인 개발자 |
| **PHP 버전 전환** | `brew link`로 수동             | GUI로 간단히 전환              |
| **로컬 도메인**    | `/etc/hosts`를 수동 편집         | 자동으로 `.test` 도메인 설정      |
| **서비스 관리**    | `brew services`             | GUI에서 기동 · 정지            |
| **커스터마이즈성**   | 높음                          | 한정적                      |

팀 개발이나 CI 환경과 설정을 맞추고 싶은 경우나, 여러 버전의 PHP를 자주 전환하는 경우에는 Homebrew에 의한 수동 구축이 적합합니다.


## Related topics

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