> ## 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 Nightwatch 入門

> 介紹 Laravel 託管 SaaS 型應用監控平台「Nightwatch」的概觀、與 Telescope／Pulse 的差異、安裝方式，以及在免費方案下實用地使用它所需的設定。

## 什麼是 Laravel Nightwatch

[Laravel Nightwatch](https://nightwatch.laravel.com) 是持續監控 Laravel 應用正式環境的**託管 SaaS 平台**。它會即時收集與可視化 HTTP 請求、SQL 查詢、例外、佇列 Job、日誌、排程任務等整個應用的遙測資料。

<Info>
  Nightwatch 是**付費服務**（月費制）。免費方案也可使用，但可收集的事件數有上限。要在免費方案下實用地使用，後述的取樣與過濾設定必不可少。
</Info>

***

## 與 Telescope、Pulse 的差異

Nightwatch 與 Laravel 生態系既有的監控／除錯工具目的不同。以下整理各自的用途。

```mermaid theme={null}
graph TD
    A["Laravel 監控工具"] --> B["Telescope<br>開發環境除錯"]
    A --> C["Pulse<br>正式環境效能彙整"]
    A --> D["Nightwatch<br>正式環境託管監控"]

    B --> B1["自架<br>僅開發時<br>免費、OSS"]
    C --> C1["自架<br>即時儀表板<br>免費、OSS"]
    D --> D1["SaaS 平台<br>需常駐 Agent<br>付費服務"]
```

| 工具             | 用途         | 託管                | 適用環境  |
| -------------- | ---------- | ----------------- | ----- |
| **Telescope**  | 開發時除錯、查詢調查 | 自架（於 Laravel 應用內） | 本機開發  |
| **Pulse**      | 效能指標彙整與顯示  | 自架（於 Laravel 應用內） | 正式、預備 |
| **Nightwatch** | 正式應用即時監控   | Laravel 託管 SaaS   | 正式環境  |

它收集的資訊與 Telescope 幾乎相同，但 Nightwatch 會讓 Agent 常駐並將資料送到雲端。因此即使伺服器當機也能查看歷史資料，也能集中管理多台伺服器、多個應用。

***

## 架構

Nightwatch 採用在 Laravel 應用與 Nightwatch 雲端之間夾入 Agent 的架構。

```mermaid theme={null}
sequenceDiagram
    participant App as Laravel 應用
    participant Agent as Nightwatch Agent<br>(php artisan nightwatch:agent)
    participant Cloud as Nightwatch 雲端
    participant Dashboard as 儀表板<br>(nightwatch.laravel.com)

    App->>Agent: 送出事件資料<br>(127.0.0.1:2407)
    Agent->>Cloud: 批次送出
    Cloud->>Dashboard: 視覺化與警示
```

Agent 於本機（`127.0.0.1:2407`）等待，接收 Laravel 應用的事件後轉送到雲端。因此需要讓 Agent 程序持續運作。

***

## 安裝與初始設定

### 1. 建立帳號與應用

於 [nightwatch.laravel.com](https://nightwatch.laravel.com) 建立帳號，並註冊組織與應用。註冊後會發行**環境 token**。

### 2. 安裝套件

```bash theme={null}
composer require laravel/nightwatch
```

與 Telescope 不同，**不需要** `--dev` flag。Nightwatch 是設計於正式環境使用。

### 3. 設定 token

於 `.env` 加入 token。

```ini theme={null}
NIGHTWATCH_TOKEN=your-api-key
```

### 4. 啟動 Agent

```bash theme={null}
php artisan nightwatch:agent
```

需讓 Agent 於背景持續執行。Laravel Cloud、Laravel Forge、Laravel Vapor 有專屬指南。Forge 使用官方整合會自動設定。

確認 Agent 狀態：

```bash theme={null}
php artisan nightwatch:status
```

### 5. 於測試環境停用

執行測試時建議停用 Nightwatch。

```ini theme={null}
# .env
NIGHTWATCH_ENABLED=false
```

也可在 `phpunit.xml` 設定。

```xml theme={null}
<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>
```

***

## 免費方案下實用使用的設定

<Warning>
  **免費方案有每月事件數上限。** 若保持預設（取樣率 100%、全部收集），流量高的應用會很快用光。請務必套用以下設定。
</Warning>

### 降低取樣率

`NIGHTWATCH_REQUEST_SAMPLE_RATE` 預設 `1.0`（全部收集）。免費方案建議降到 `0.1`（10%）左右。

```ini theme={null}
# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
```

例外與指令仍全部收集的設定範例：

```ini theme={null}
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # 只收 10% 請求
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # 例外全收（預設）
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # 指令全收（預設）
```

### 停用查詢收集

資料庫查詢占事件量的大宗。免費方案下停用查詢收集，可留下更多空間收重要事件（例外、請求、Job）。

```ini theme={null}
# .env
NIGHTWATCH_IGNORE_QUERIES=true
```

### 其他過濾設定

視需要也可停用快取事件或郵件收集。

```ini theme={null}
NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true
```

### 免費方案推薦設定總覽

```ini theme={null}
# .env（免費方案推薦設定）
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
```

只要設好這 3 行，免費方案也能實用地做應用監控。

***

## 主要功能

### 請求監控

依每個 HTTP 請求收集回應時間、狀態碼、路由資訊等。可找出異常慢的 endpoint、發現效能瓶頸。

### 例外追蹤

即時捕捉正式環境未處理的例外。堆疊追蹤與原始碼片段會自動記錄，便於原因調查。

```ini theme={null}
# 例外原始碼收集（預設啟用）
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```

### 日誌收集

與 Laravel 日誌系統（如 `Log::error()`）整合，把結構化日誌送到 Nightwatch。

```ini theme={null}
# 收集的日誌最低等級（預設：debug）
NIGHTWATCH_LOG_LEVEL=error
```

### Job 與排程任務監控

追蹤佇列 Job 與排程任務的執行紀錄、成功／失敗狀態、執行時間，能快速找出批次處理問題。

### 部署追蹤

把每次發佈的變更與問題連結起來，能可視化查詢「這次部署後例外變多了」這類問題。

### 警示與通知

可搭配 Slack 整合或 Webhook，於例外爆增或效能劣化時立即通知。

***

## Telescope 與 Nightwatch 的使用時機

```mermaid theme={null}
flowchart TD
    Q1{"需要正式環境<br>的資料？"} -->|是| Q2{"想把資料放在<br>自己的伺服器？"}
    Q1 -->|否| T["Telescope<br>（本機開發）"]
    Q2 -->|是| P["Pulse<br>（自架）"]
    Q2 -->|否| N["Nightwatch<br>（託管 SaaS）"]
```

* **本機開發** → Telescope
* **想要正式環境彙整儀表板** → Pulse
* **想要正式環境詳細追蹤與警示** → Nightwatch

三者並非互斥，Pulse 與 Nightwatch 可以併用。

***

## 總結

Laravel Nightwatch 是大幅提升正式 Laravel 應用可觀測性的強大 SaaS。導入時請注意以下幾點：

* 需要讓 Agent 程序常時運作
* 免費方案幾乎必設 `NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1` 與 `NIGHTWATCH_IGNORE_QUERIES=true`
* Telescope（開發）、Pulse（彙整）、Nightwatch（監控）角色不同，可以併用

詳細設定請參考[官方文件](https://nightwatch.laravel.com/docs/start-guide)與[環境變數參考](https://nightwatch.laravel.com/docs/environment-variables)。

<Card title="Laravel Telescope 實務技巧" icon="telescope" href="/zh-TW/blog/telescope-introduction">
  本機開發除錯請使用 Telescope。
</Card>


## Related topics

- [Laravel AI Agent 支援 MCP 伺服器](/zh-TW/blog/ai-sdk-mcp-client.md)
- [部落格](/zh-TW/blog/index.md)
- [入門 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/getting-started.md)
- [React 入門 — 搭配 Inertia × Laravel 使用的基礎知識](/zh-TW/blog/react-introduction.md)
- [Svelte 入門 — 搭配 Inertia × Laravel 使用的基礎知識](/zh-TW/blog/svelte-introduction.md)