> ## 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 上會自動在 shell 設定檔（如 `~/.zprofile`）加入以下行。若需要手動加入，請重新載入設定。

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

確認安裝：

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

***

## 安裝 PHP

<Steps>
  <Step title="安裝最新 PHP">
    Homebrew 的 `php` formula 始終指向最新穩定版。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 版本，可安裝帶版本的 formula。

    ```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 Installer）可用，把 `~/.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="於 shell 設定檔加入設定">
    安裝腳本會自動於 `~/.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 Installer">
    ```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）](/zh-TW/blog/windows-setup.md)
- [部落格](/zh-TW/blog/index.md)
- [博客](/zh-CN/blog/index.md)
- [安裝](/zh-TW/installation.md)
- [以 Vite 進行 asset bundling](/zh-TW/vite.md)