Laravel Doctor，用一条 artisan 命令诊断应用
Laravel Doctor 于 2026 年在波士顿举办的 Laracon US 上发布，新增了一条 artisan doctor 命令，用于对应用运行健康检查。以下内容摘自发布公告：
artisan doctor 会对 Laravel 应用运行一组健康检查：APP_KEY 是否已设置、PHP 版本是否与 Composer 期望一致、所需扩展是否已安装、环境配置是否完整？凡能自动修复的问题，它会直接修复；凡无法修复的问题，它会明确指出问题所在。
诊断一个出问题的 Laravel 安装，过去通常意味着对照一份脑内清单逐一排查：.env 是否存在、key 是否已生成、storage/ 目录是否可写、生产环境的队列连接是否不是 sync。Doctor 把这份清单变成了代码，并让各扩展包有机会把自己的检查项加入其中。
工作原理
每条诊断都是一个独立的类，只检查一件事，并返回六种状态之一：pass、notice、warn、fail、skip 或 error。默认情况下，只要发生任何失败或错误，命令就会以非零状态码退出。如果希望警告也导致构建失败，可传入 --fail-on=warn。如果只想得到报告、绝不希望得到失败的退出码，则使用 --fail-on=never。
随附的检查套件覆盖以下方面：
- 环境（Environment）：.env 是否存在、APP_KEY、PHP 版本是否满足 composer.json 中的约束、必需与推荐扩展，以及时区。
- Composer：依赖是否已安装、能否转储优化的 autoload 文件，以及可修复的 composer.lock 问题。
- 配置（Configuration）：配置文件能否加载与缓存、活动驱动所需的配置值是否已设置，以及 bootstrap 缓存状态。
- 数据库（Database）：默认连接是否可达、需要时 SQLite 文件是否存在，以及是否有待执行的迁移。
- 缓存、队列、调度器与会话：已配置的驱动是否可达、Redis 连接是否正常，以及以 notice 形式展示计划任务。
- 存储（Storage）：默认磁盘是否可达、所需目录是否可写，以及 storage:link 符号链接是否存在。
- 安全（Security）：调试模式是否与当前环境匹配、.env 是否已被 git 忽略，以及依赖是否经过审计。
其中有些检查无法孤立地作出判断，因此 Doctor 会把应用解析为两种模式之一：本地（local）或生产（production），再由模式决定某项结果是否算作问题。sync 队列连接在本地判定为通过，在生产环境则给出警告。缺失的 bootstrap 缓存在生产环境产生警告、在本地则通过；已存在的缓存则相反——在生产环境通过、在本地产生一条 notice，因为过期的缓存是开发过程中最近改动迟迟不生效的常见原因。Laravel Doctor 开箱即能识别本地、生产与预发（staging）环境，凡是它无法识别的环境，一律按生产标准来要求。
快速上手
将其安装为开发依赖：
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 存储链接，并修复存储目录权限。其他修复则需要人工在选项中作出选择，例如当默认缓存存储不可达时改用哪一个缓存存储。这类选项在交互式运行命令时以选择列表的形式呈现，而在 --fix 模式下则退化为普通失败。
诊断结果可以按类名、分组、扩展包或扩展包通配符进行过滤：
php artisan doctor --only=securityphp artisan doctor --except=laravel/*如果希望始终应用同一组选择器，可用 php artisan vendor:publish --tag=doctor-config 发布配置文件，并在其中统一设置。
自定义诊断
扩展包可以通过 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 并实现一个返回 DiagnosticResult 的 check() 方法。文案则单独放在 messages() 方法中，其中每个 Message::make() 都包含摘要、修复说明、文档链接，以及修复执行前显示的确认提示。
如果检查项能够修复发现的问题，可实现 Laravel\Doctor\Contracts\Fixable 接口，并用 ->fixable() 标记具体失败项。该方法还接受一个 EnvironmentMode 参数，因此可以把修复限定在开发者机器上执行。
面向 CI 与 AI 代理的输出
CLI 输出是默认形式，但 --format=json 可以生成机器可读的报告，--format=github 则生成 GitHub Actions 注解。Doctor 在这两种格式下都会拒绝 --fix，从而保证面向机器的报告绝不会修改应用。
还有第四种格式，面向编码代理；当 Laravel Agent Detector 检测到 Doctor 运行在 Claude Code 或 Cursor 之类的环境中时，它会自动切换为这种格式。该格式遵循 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 编码代理顺理成章的收官一步：完成改动后，代理可以运行一次 artisan doctor 作为最终健全性检查，再判定任务是否完成。
任何被标记为可修复的问题，都可以通过带 --fix 重新运行来解决：它会应用修复、重新运行诊断，并把结果追加到载荷中。任何带回选项映射的结果都需要 --fix 不会自行作出的选择，这时代理要么自己遵循修复说明，要么把备选清单交给人类处理。如要在没有代理的情况下查看该格式，可运行 AI_AGENT=test php artisan doctor。
Doctor 也可以脱离 artisan 命令运行。Doctor::run() 返回一个 DiagnosticReport，only()、except()、bail() 和 fixUsing() 可以从程序层面约束这次运行。
了解更多
Laravel Doctor 要求 PHP 8.3 以及 Laravel 12 或 13，采用 MIT 许可证。完整文档，包括 Laravel\Doctor\Support 中的诊断辅助工具，以及编写自定义检查的完整指南，都位于 Laravel Doctor 的 GitHub 仓库中。
