> ## 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(默认发行版)。完成后重启电脑。
  </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 版本之间切换">
    如果需要多个 PHP 版本,可以用 `update-alternatives` 切换。

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

    列出已安装的版本,输入要使用版本对应的编号。
  </Step>
</Steps>

***

## 安装 Composer

使用官方 installer 安装 Composer。

<Steps>
  <Step title="确认必要的包">
    ```bash theme={null}
    sudo apt install -y curl php8.3-cli unzip
    ```
  </Step>

  <Step title="下载并执行官方 installer">
    ```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 installer),把 `~/.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="在 shell 配置里追加">
    安装脚本会自动向 `~/.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 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 欢迎页就完成了。

    <Tip>
      如果 WSL 中的服务在 Windows 浏览器里无法访问 `localhost`,可以尝试用 `php artisan serve --host=0.0.0.0` 启动。
    </Tip>
  </Step>
</Steps>

***

## 补充:提升开发效率的工具

### Windows Terminal

Windows Terminal 让你能用多个 tab 集中管理 WSL、PowerShell、命令提示符。可以从 Microsoft Store 免费安装。

* 在 tab 中并行操作多个 shell
* 可以把 Ubuntu shell 设为默认
* 字体和配色可自由定制

### VS Code Remote - WSL 扩展

用 VS Code 的 [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) 扩展,可以在 Windows 的 VS Code 中直接编辑 WSL 里的文件。

```bash theme={null}
# 在 WSL 终端里用 VS Code 打开项目
code .
```

首次执行时,VS Code 会自动在 WSL 里安装 VS Code Server。之后就能获得几乎和原生一致的开发体验。


## Related topics

- [用 Homebrew 安装 PHP、Composer 和 Node.js(macOS)](/zh/blog/mac-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)