> ## 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 查询、异常、队列作业、日志、定时任务等应用整体的遥测数据。

<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>免费 / 开源"]
    C --> C1["自托管<br>实时仪表盘<br>免费 / 开源"]
    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` 标志。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    # 命令全量(默认)
```

### 关闭 query 采集

数据库查询占用的事件量往往非常大。免费额度下关掉查询采集,能为异常、请求、作业等重要事件腾出空间。

```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 请求采集响应时间、状态码、路由信息等。可以定位异常慢的端点,发现性能瓶颈。

### 异常追踪

实时捕获生产环境中的未处理异常。自动记录堆栈跟踪与源代码片段,方便排查原因。

```ini theme={null}
# 异常源代码采集(默认启用)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```

### 日志采集

与 Laravel 的日志系统(`Log::error()` 等)集成,把结构化日志发送到 Nightwatch。

```ini theme={null}
# 采集日志的最低级别(默认:debug)
NIGHTWATCH_LOG_LEVEL=error
```

### 作业与定时任务监控

追踪队列作业、定时任务的执行历史、成功/失败状态、执行时间。可以快速定位批处理问题。

### 部署追踪

把每次发布的变更与问题关联起来。可以直观地进行“这次部署之后异常增加了”一类的排查。

### 告警与通知

通过 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/blog/telescope-introduction">
  本地开发调试请使用 Telescope。
</Card>


## Related topics

- [React 入门 —— 与 Inertia × Laravel 搭配使用的基础](/zh/blog/react-introduction.md)
- [Svelte 入门 —— 与 Inertia × Laravel 搭配使用的基础](/zh/blog/svelte-introduction.md)
- [Vue.js 入门 —— 与 Inertia × Laravel 搭配使用的基础](/zh/blog/vue-introduction.md)
- [Laravel Cloud — Laravel 专用 PaaS 全貌](/zh/blog/laravel-cloud.md)
- [laravel/agent-skills — Laravel 官方 AI 智能体技能集](/zh/blog/agent-skills-introduction.md)