必须确认php≥8.1、storage与bootstrap/cache可写、.env无空值，任一缺失均导致静默500错误；需用php -v和php -m验证版本及openssl、pdo等扩展；禁用生产环境直接composer install，改用本地构建vendor后上传；nginx须正确配置root指向public、try_files重写及fastcgi_param script_filename；config:cache失败时先清缓存、语法检查.env再排查驱动依赖。
直接上生产环境前，必须确认 PHP 版本 ≥8.1、storage 和 bootstrap/cache 可写、.env 里没留空值（比如 DB_PASSWORD= 后面什么都没有），三者任一出错，500 页面不报错也不打日志，只能靠猜。
检查 PHP 环境和扩展是否齐全
很多 500 错误根本不是代码问题，而是 PHP 缺扩展或版本太低。Laravel 12 要求 PHP ≥8.2，且必须启用：openssl、pdo、mbstring、tokenizer、xml、ctype、json、fileinfo、bcmath、gmp。
执行命令快速验证：
php -v<br>php -m | grep -E 'openssl|pdo|mbstring|tokenizer|xml|ctype|json|fileinfo|bcmath|gmp'
如果漏了某个扩展，Ubuntu/Debian 下装 php-mbstring 这类包后，要重启 php-fpm 服务才生效；CentOS/RHEL 则需确认 php.ini 里没注释掉对应 extension= 行。
部署代码时别用 composer install 直接在服务器跑
本地开发机性能好，composer install 慢点无所谓；但生产服务器资源紧张，又装一堆 dev 包（如 phpunit、laravel/pint），既拖慢启动，又增加攻击面。
推荐做法是：本地先执行完所有构建步骤，再传完整 vendor 上去：
- 本地运行
composer install --no-dev --optimize-autoloader - 删掉
node_modules和.git（除非你真需要在服务器 git 操作） - 打包上传，或用
rsync -avz --delete同步 - 服务器上不再运行
composer install，只跑php artisan key:generate和缓存命令
这样能绕过服务器网络不稳定、内存不足导致的 Composer 安装失败，也避免 autoload_classmap.php 生成不全引发的类找不到错误。
Nginx 配置里这三行不能少，也不能抄错
Laravel 的路由重写机制很脆弱，网上很多 Nginx 配置只写了 root 和 index，结果除首页外全 404——问题就出在这三行：
-
try_files $uri $uri/ /index.php?$query_string;—— 没它，静态资源能访问，PHP 路由全崩 -
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;—— 必须用$realpath_root，否则 symlink 路径下会 502 -
fastcgi_split_path_info ^(.+\.php)(/.+)$;—— 不加它，带路径参数的 API（如/api/v1/users/123）会进错脚本
另外，root 必须指向项目 public/ 目录，绝对不能是项目根目录；否则 .env、config/ 全暴露在 Web 下，秒变高危。
php artisan config:cache 失败时别硬跑
这个命令看似只是“缓存配置”，实则会解析整个 .env 并写入 bootstrap/cache/config.php。一旦 .env 里有语法错误（比如 APP_URL=https:// 少了域名）、变量未定义（REDIS_HOST= 后面空着）、或用了未安装的扩展（CACHE_DRIVER=redis 但没装 php-redis），就会静默失败，后续所有 artisan 命令都卡住或报错。
排查顺序固定：
- 先运行
php artisan config:clear清掉旧缓存 - 再执行
php -l .env检查语法（注意：它只查基础格式，不校验变量值） - 然后手动检查每个
=右侧有没有空格、引号不配对、特殊字符没转义 - 最后确认
php -m输出里真有redis或memcached（取决于你配的驱动）
很多人卡在这里反复重试，其实只要把 .env 里非必要项（如邮件、第三方 SDK）先注释掉，最小化验证通过后再逐步放开。
最常被跳过的其实是 chown 权限——www-data 用户得同时拥有 storage 和 bootstrap/cache 的写权限，而不仅仅是 chmod 755；否则日志写不进 storage/logs，队列任务卡在 failed_jobs 表里不动，连问题都看不到。
