> ## 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 Telescope

> 說明 Laravel Telescope 的導入。涵蓋本機專用安裝與 watcher 配置。

## 什麼是 Laravel Telescope

[Laravel Telescope](https://github.com/laravel/telescope) 是可視化 Laravel 應用內部狀態的官方除錯工具。
可詳細記錄請求、例外、查詢、job、log、mail、通知、快取操作、排程執行等。

它是**本機開發環境專用**的除錯工具。正式環境的監控請使用 [Laravel Pulse](/zh-TW/pulse) 或 [Laravel Nightwatch](/zh-TW/blog/nightwatch-introduction)。

### 監控對象層

```mermaid theme={null}
flowchart LR
    A["HTTP 層<br>Request / Response"] --> T["儲存 Telescope entry"]
    B["應用層<br>Events / Logs / Exceptions"] --> T
    C["資料層<br>DB Queries / Redis / Cache"] --> T
    D["非同步層<br>Queue Jobs / Schedule / Notifications"] --> T
    T --> E["儀表板<br>/telescope"]
```

***

## 安裝

<Steps>
  <Step title="安裝 Telescope">
    ```shell theme={null}
    composer require laravel/telescope
    ```
  </Step>

  <Step title="發布 asset 與 migration">
    ```shell theme={null}
    php artisan telescope:install
    ```
  </Step>

  <Step title="執行 migration">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

安裝後可透過 `/telescope` 存取儀表板。

## 本機專用安裝（建議）

<Info>
  若主要目的是本機除錯，建議以 `--dev` 安裝，並僅在 `local` 環境手動登記 service provider 的組態。
</Info>

```shell theme={null}
composer require laravel/telescope --dev

php artisan telescope:install
php artisan migrate
```

`telescope:install` 執行後，請從 `bootstrap/providers.php` 移除 `TelescopeServiceProvider` 的登記。
然後於 `App\Providers\AppServiceProvider` 的 `register` 方法手動登記。

```php theme={null}
public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}
```

還要在 `composer.json` 停用 auto-discovery。

```json theme={null}
{
  "extra": {
    "laravel": {
      "dont-discover": [
        "laravel/telescope"
      ]
    }
  }
}
```

***

## 可用的 Watcher

Watcher 會蒐集請求或指令執行時的遙測資料。
於 `config/telescope.php` 管理啟用與設定。

<AccordionGroup>
  <Accordion title="Request Watcher">
    記錄請求、header、session、回應。\
    可用 `size_limit` 限制回應記錄大小。
  </Accordion>

  <Accordion title="Query Watcher（特別重要）">
    記錄 SQL、bindings、執行時間。\
    預設超過 **100ms** 的查詢會被以 `slow` 標籤記錄，對偵測效能瓶頸非常有效。

    ```php theme={null}
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ```
  </Accordion>

  <Accordion title="Job Watcher">
    記錄 queue job 的送出與執行結果。
  </Accordion>

  <Accordion title="Exception Watcher">
    記錄可回報的例外與 stack trace。
  </Accordion>

  <Accordion title="Log Watcher">
    記錄應用程式的 log。\
    預設為 `error` 以上，可透過設定降至 `debug`。
  </Accordion>

  <Accordion title="Command Watcher">
    記錄 Artisan 指令的引數、選項、輸出、結束碼。
  </Accordion>

  <Accordion title="Event Watcher">
    記錄 dispatch 的事件 payload 與 listener 資訊（排除 Laravel 內部事件）。
  </Accordion>

  <Accordion title="Cache Watcher">
    記錄快取的命中、未命中、更新、刪除。
  </Accordion>

  <Accordion title="Redis Watcher">
    記錄應用執行的 Redis 指令。
  </Accordion>

  <Accordion title="Model Watcher">
    記錄 Eloquent model 事件，並可視情況蒐集 hydration 筆數。
  </Accordion>

  <Accordion title="Notification Watcher">
    記錄送出的通知。
  </Accordion>

  <Accordion title="Mail Watcher">
    可在瀏覽器預覽送出的信件，並下載為 `.eml`。
  </Accordion>

  <Accordion title="HTTP Client Watcher">
    記錄對外的 HTTP client 請求。
  </Accordion>

  <Accordion title="Gate Watcher">
    記錄 Gate / Policy 的授權檢查結果。
  </Accordion>

  <Accordion title="Schedule Watcher">
    記錄排程執行的指令與輸出。
  </Accordion>

  <Accordion title="View Watcher">
    記錄已渲染的 view 名稱、路徑、資料、composer。
  </Accordion>

  <Accordion title="Batch Watcher">
    記錄 queue batch 資訊（job 或連線資訊）。
  </Accordion>

  <Accordion title="Dump Watcher">
    當 Telescope 的 Dump 分頁開啟期間，記錄 `dump` 輸出。
  </Accordion>
</AccordionGroup>

***

## 總結

| 任務      | 建議設定                                       |
| ------- | ------------------------------------------ |
| 導入      | `composer require laravel/telescope --dev` |
| 確實限制在本機 | 手動登記 provider + `dont-discover`            |
| DB 效能調查 | 活用 Query Watcher 的 slow query 標籤（預設 100ms） |

## 後續步驟

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/zh-TW/pulse">
    導入正式環境的效能集計儀表板。
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/zh-TW/blog/nightwatch-introduction">
    以 Nightwatch 進行正式環境即時監控。
  </Card>
</Columns>


## Related topics

- [Laravel Telescope 實戰技巧](/zh-TW/blog/telescope-introduction.md)
- [Laravel Pulse](/zh-TW/pulse.md)
- [Laravel Nightwatch 入門](/zh-TW/blog/nightwatch-introduction.md)
- [用 Laravel 構建 MCP 伺服器](/zh-TW/advanced/mcp-server.md)
- [套件的版本相容性管理](/zh-TW/advanced/package-versioning.md)