> ## 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/blog/windows-setup.md)
- [安装](/zh/installation.md)
- [Laravel 11 升级到 12 指南](/zh/blog/upgrade-11-to-12.md)
- [使用 Vite 打包资源](/zh/vite.md)
- [用 Pest PHP 开始 Laravel 测试](/zh/blog/pest-introduction.md)