Laravel Doctor：用一条 Artisan 命令诊断你的应用

Laravel Doctor 在波士顿举行的 Laracon US 2026 大会上正式发布，它引入了一个 artisan doctor 命令，用于对您的应用程序进行健康检查。根据发布公告：

artisan doctor 会对 Laravel 应用执行一系列健康检查：例如 APP_KEY 是否已设置、PHP 版本是否符合 composer.json 的要求、必要的扩展是否已安装，以及环境配置是否完整。如果问题可以自动修复，它会直接进行修复；如果无法自动修复，它会明确指出问题所在。

过去，排查 Laravel 安装故障通常需要对照一份“心里的清单”：.env 文件是否存在、密钥（key）是否已生成、storage/ 目录是否可写、生产环境中的队列连接是否未设置为 sync 模式等。Doctor 将这份清单转化为了代码，并允许扩展包向其中添加自定义的检查项。

工作原理

每一项诊断都是一个独立的类，负责检查特定内容并返回六种状态之一：通过（pass）、提示（notice）、警告（warn）、失败（fail）、跳过（skip）或错误（error）。默认情况下，如果出现“失败”或“错误”状态，该命令将以非零状态码退出。如果你希望“警告”也导致构建失败，可以传入 --fail-on=warn 参数；如果您只想查看报告而不希望出现失败退出码，则可以使用 --fail-on=never。

内置的检查套件涵盖了以下方面：

环境：.env 文件的存在性、APP_KEY、PHP 版本与 composer.json 约束的匹配情况、必要及推荐的扩展、时区设置。
Composer：依赖项是否已安装、自动加载（autoload）文件是否可优化生成、以及可修复的 composer.lock 问题。
配置：配置文件加载与缓存、当前驱动程序所需的值是否已设置、引导缓存（bootstrap cache）状态。
数据库：默认连接是否可达、SQLite 文件（如需）是否存在、是否存在待执行的迁移（migrations）。
缓存、队列、调度器和会话：配置的驱动程序是否可达、Redis 连接检查、以及将计划任务列为提示信息。
存储：默认磁盘是否可达、必要目录是否可写、storage:link 软链接是否存在。
安全：调试模式与环境是否匹配、.env 是否已加入 Git 忽略列表、依赖项审计。

其中一些检查无法孤立进行，因此 Doctor 会将您的应用判定为“本地（local）”或“生产（production）”模式，并根据该模式决定某项检查结果是否被视为问题。使用 sync 队列连接时，检查会在本地环境通过，但在生产环境发出警告；缺失引导缓存（bootstrap caches）会在生产环境发出警告，但在本地环境通过；而已存在的缓存会在生产环境通过，但在本地环境产生提示信息——因为缓存过期是导致开发过程中所做更改无法生效的常见原因。Laravel Doctor 开箱即支持识别本地、生产和预发布（staging）环境，对于无法识别的环境，则默认按生产环境的标准进行检查。

入门指南

将其作为开发依赖（dev dependency）安装：

composer require laravel/doctor --dev

然后运行：

php artisan doctor

当诊断发现的问题可以修复时，Doctor 会报告该问题，并在采取任何行动前提示您：

Storage is writable: The application cannot write to every required storage directory.
 
 Make the storage directories writable? (yes/no) [yes]

使用 php artisan doctor --fix 命令时会跳过交互式提示。该命令可自动执行以下操作：创建缺失的 .env 文件、生成 APP_KEY、在生产环境中关闭调试模式、将 .env 添加到 .gitignore、创建公共存储（public storage）软链接以及修复 storage 目录的权限。其他修复操作则需要人工选择，例如当默认缓存存储不可用时选择切换到哪个缓存存储；在交互模式下运行命令时，这些选项会以列表形式呈现，而在使用 --fix 模式时，若无法自动处理，则会视为修复失败。

诊断任务可以根据类名、组名、包名或包名通配符进行筛选：

php artisan doctor --only=security
 
php artisan doctor --except=laravel/*

如果你希望始终应用相同的选择器，请运行 php artisan vendor:publish --tag=doctor-config 发布配置文件，并在其中进行设置。

自定义诊断

扩展包可以通过其服务提供者（Service Provider）利用 Doctor 门面（Facade）注册诊断，方式与应用程序相同：

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;
 
public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}

报告显示了每项诊断信息源自哪个 Composer 包：

[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[pass] SQLite database exists (acme/application): The SQLite database file exists.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.

运行 php artisan make:diagnostic HorizonIsRunning 命令会在 app/Doctor/Diagnostics 目录下生成相应的诊断类。该类继承自 Laravel\Doctor\Diagnostic 并实现 check() 方法，该方法返回一个 DiagnosticResult 对象。相关的文本信息定义在 messages() 方法中，其中每个 Message::make() 调用都包含了摘要、修复建议、文档链接以及执行修复前显示的确认提示。

如果你的诊断项具备自动修复功能，请实现 Laravel\Doctor\Contracts\Fixable 接口，并使用 ->fixable() 标记具体的失败项。该方法还接受 EnvironmentMode 参数，从而可以将修复操作限制在开发环境（开发者机器）中执行。

针对 CI 和 AI Agent 的输出

默认输出为 CLI 格式，但使用 --format=json 可生成机器可读的报告，使用 --format=github 则生成 GitHub Actions 注解。当使用这两种格式时，Doctor 不允许使用 --fix 参数，以确保旨在供机器读取的报告不会导致应用程序发生变更。

此外还有第四种专为编码 Agent 设计的格式；当 Laravel Agent Detector 检测到程序运行在 Claude Code 或 Cursor 等环境中时，Doctor 会自动切换至该格式。该格式遵循 Laravel PAO 规范：单行 JSON 输出，包含预先统计的计数信息，且仅列出可采取行动的具体结果项。

{"tool":"doctor","result":"failed","diagnostics":27,"failed":1,"warnings":1,"notices":0,"passed":19,"skipped":6,"issues":[{"name":".env file exists","status":"fail","summary":"The application does not have an environment file.","fix":"Run `cp .env.example .env`, then review the copied values.","fixable":true}]}

这引出了公告的其余部分：

软件包可以注册自己的诊断检查，因此具有特定配置要求的软件包可以直接接入 artisan doctor，并将其自身的健康检查与框架内置的检查一并呈现。对于 AI 编码智能体（AI coding agents）而言，这也是一个自然的收尾步骤：智能体在进行更改后，可以在认定任务完成之前运行 artisan doctor，作为最后一道“健全性检查”（sanity check）。

任何被标记为“可修复”的问题，都可以通过带 --fix 参数重新运行命令来解决；该参数会应用修复措施、重新运行诊断，并将结果附加到输出负载中。对于那些返回选项映射（options map）的问题，则需要做出 `fix` 无法自动决定的选择；此时，智能体既可以自行按照修复建议进行操作，也可以将候选方案列表提交给人工处理。若想在不使用智能体的情况下查看输出格式，可运行 AI_AGENT=test php artisan doctor。

Doctor 也可以脱离 Artisan 命令直接运行。`Doctor::run()` 会返回一个 DiagnosticReport 对象，开发者可以通过 only()、except()、bail() 和 fixUsing() 等方法以编程方式控制运行过程。

了解更多