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

# Laravel Multiplex — 統一管理本地開發程序的 TUI

> laravel/multiplex 的初期調查。解說 Laravel 13 的 php artisan dev 所使用、支援多程序 tab 顯示、搜尋與自動重啟的終端機 UI。

## 前言

[`laravel/multiplex`](https://github.com/laravel/multiplex) 是同時執行多個指令的終端機 UI（TUI）。Laravel 13 的 `php artisan dev` 會利用它，讓 PHP 開發伺服器、佇列 worker、日誌監看、Vite 等本地開發所需的程序，都能在同一個終端機中管理。

每個程序的輸出可用 tab 顯示，並支援輸出的搜尋與捲動。結束時，各程序的輸出會被寫回一般終端機的 scrollback，因此關閉 TUI 之後仍可確認日誌。

## 安裝與直接執行

在 Laravel 應用中，`php artisan dev` 會處理必要設定，通常不需要直接安裝 Multiplex。若要單獨使用，請準備 Node.js 22.13 以上並用 npm 安裝。

```bash theme={null}
npm install -g @laravel/multiplex
```

指令以 `label,command` 格式傳入。

```bash theme={null}
multiplex 'server,php artisan serve' 'queue,php artisan queue:listen' 'vite,npm run dev'
```

## TUI 與 inline 模式

當標準輸入與標準輸出為 TTY 時，會啟動 tab 型 TUI。可用 `s` 切換為 stream 顯示、`/` 搜尋輸出、`r` 重啟選取中的程序，並以 `q` 結束。

在沒有 TTY 的 CI 或 pipe 處理中，會自動切換為 inline 模式。每一行會附上程序的 label，並依輸出到達的順序顯示。若要明確使用 inline 模式，請指定 `-i`。

```bash theme={null}
multiplex -i 'build,npm run build' 'test,npm test'
```

在 inline 模式下，最後一個程序結束時執行也會結束，並將指令的失敗反映在 exit code 上。若要以 JSON 格式處理結果，可使用 `--json`。

```bash theme={null}
multiplex --json 'build,npm run build' 'test,npm test'
```

## 自動重啟與結束處理

崩潰的程序會等待 1 秒後自動重啟，最多重試 5 次。啟動後 1 秒內就結束的程序，可能是執行檔缺失或連接埠衝突等從一開始就無法啟動的情況，因此不會重試。對於 build 或 migration 這類只執行一次的指令，請指定 `--no-restart`。

```bash theme={null}
multiplex --no-restart 'build,npm run build'
```

Multiplex 在結束或收到 signal 時，會終止子程序的 process group。可避免只剩開發伺服器仍佔用連接埠的情況，將多個程序一起停止。

## 注意事項

子程序不會被傳入標準輸入。因此 `php artisan tinker` 或 migration 的確認 prompt 等需要輸入的指令，無法從 Multiplex 執行。互動式指令請在另一個終端機執行。

Multiplex 也提供程式化 API，但指令是以 `sh -c` 執行。請勿將設定檔或 request 等不可信的值嵌入指令字串。

## 參考資料

* [Laravel 官方文件：Artisan - The Dev Command](https://laravel.com/docs/13.x/artisan#the-dev-command)
* [laravel/multiplex README](https://github.com/laravel/multiplex)


## Related topics

- [Artisan Console](/zh-TW/artisan.md)
- [WebSocket (Jetstream / Firehose)](/zh-TW/packages/laravel-bluesky/websocket.md)
- [Eloquent Observer 與模型事件](/zh-TW/advanced/eloquent-observers.md)
- [Laravel Head](/zh-TW/head.md)
- [資料庫 Seeding](/zh-TW/seeding.md)