php artisan doctor是laravel官方2026年起强制推行的上线前检查命令，可拦截app_debug=true、queue_connection=sync等高危配置，但不自动修复关键项；它检测php版本与扩展、环境变量、缓存驱动等，却无法覆盖web服务器配置、fpm权限、docker卷挂载等部署层问题。
上线前不跑一遍检查清单，等于把生产环境当测试机用。 Laravel 官方从 2026 年起已将这套经验固化为 php artisan doctor 命令——它不是锦上添花的玩具，而是能直接拦截 APP_DEBUG=true、QUEUE_CONNECTION=sync 这类高危配置的守门人。
哪些配置项必须人工核对，doctor 不会替你改
有些关键项 doctor 只报 warn 或 fail，但不会自动修正，因为改错可能直接导致服务不可用：
-
.env中的APP_ENV必须是production，且APP_DEBUG=false——doctor 会 fail，但绝不帮你设成 false -
QUEUE_CONNECTION在生产中不能是sync，doctor 在生产模式下对此直接 warn；但它不会帮你切到redis或database -
CACHE_DRIVER和SESSION_DRIVER若仍为file或array，doctor 会报 notice，但切换需你确认缓存服务（如 Redis）是否已就绪 -
STORAGE_PATH和BOOTSTRAP_CACHE_PATH的写权限：doctor 能检测storage/logs是否可写，但不会自动chown或chmod
doctor 检查不了，但部署时必踩的坑
这类问题不在 doctor 覆盖范围内，却高频导致上线后 500 或白屏：
- Nginx/Apache 未正确指向
public/目录，或重写规则缺失 ——try_files $uri $uri/ /index.php?$query_string少一个字符都进不了路由 -
php-fpm用户与storage/目录属主不一致，比如 fpm 以www-data运行，但目录属主是root，doctor 检测的是“可写”，不是“被谁写” -
config:cache和route:cache执行后，若后续改了.env却没重新缓存，新配置不会生效 —— doctor 不管缓存是否过期，只管当前文件是否存在 - Docker 环境下，
docker-compose.yml里 PHP 容器没挂载storage/和bootstrap/cache/到宿主机，重启容器后缓存全丢，doctor 每次都在“干净”容器里跑，看不出问题
PHP 环境本身是否达标，doctor 会查但容易被忽略
doctor 默认检查 PHP 版本和必需扩展，但以下细节常被跳过：
- PHP 版本必须 ≥8.1（Laravel 10+ 强制要求），但
php -v显示 8.1.x 不代表 CLI 和 FPM 用的是同一版本 —— 运行php-fpm -v或在phpinfo()页面确认 - 扩展
ext-pdo、ext-mbstring、ext-openssl是硬性依赖，但php -m列出的扩展名可能带版本后缀（如mbstring.sovsmbstring-8.1.so），doctor 严格匹配模块名，拼错就判 fail -
opcache.enable=1和opcache.validate_timestamps=0（生产应关）不在 doctor 检查范围，但没开 opcache 会导致视图渲染慢 3–5 倍
真正卡住上线的，往往不是 doctor 报出来的 error，而是它根本没机会看到的地方：Web 服务器配置错位、FPM 用户权限错配、Docker 卷挂载遗漏。这些没法靠一条命令兜底，得在部署脚本里固化检查步骤，或者把 doctor 加进 CI 的 deploy:precheck 阶段，而不是等 SSH 登上去再手动敲。
