> ## 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 標準 repository 的 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 使用官方 installer 安裝。

<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">
    最新的安裝 script 可於 [nvm 的 GitHub repository](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 設定檔">
    安裝 script 會自動在 `~/.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="設定為預設">
    為了讓新的終端 session 也自動使用，設定預設版本。

    ```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
    ```

    會啟動互動式設定。可選擇 starter kit 或是否啟用認證等。
  </Step>

  <Step title="啟動開發伺服器">
    ```bash theme={null}
    cd my-app
    php artisan serve
    ```

    在瀏覽器開啟 `http://localhost:8000`，若顯示 Laravel 歡迎頁面即完成。

    <Tip>
      若無法從 Windows 瀏覽器透過 WSL 存取 `localhost`，請嘗試以 `php artisan serve --host=0.0.0.0` 啟動。
    </Tip>
  </Step>
</Steps>

***

## 補充：提升開發效率的工具

### Windows Terminal

使用 Windows Terminal 可透過多個分頁一次管理 WSL、PowerShell、命令提示字元。可從 Microsoft Store 免費安裝。

* 以分頁並行操作多個 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 server 會自動安裝到 WSL 內。之後可享有與原生同等的操作體驗進行開發。


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [博客](/zh-CN/blog/index.md)
- [使用 Homebrew 安裝 PHP、Composer、Node.js（macOS）](/zh-TW/blog/mac-setup.md)
- [安裝](/zh-TW/installation.md)
- [以 Vite 進行 asset bundling](/zh-TW/vite.md)