laravel项目上线最常卡在权限、环境变量和web服务器配置三处：php版本与扩展必须≥8.1且齐全，.env须置于根目录并设app_env=production、app_debug=false，nginx的root必须精确指向public目录并启用重写。
php artisan key:generate 跑不通、storage 目录写不进日志、Nginx 打开页面是 403 或 500——这些都不是代码问题，而是部署链路上的“默认值陷阱”。
本地开发前必须确认的 4 个 PHP 环境项
别跳过这步，否则后面所有命令都会报错或静默失败：
-
php -v输出必须 ≥ 8.1（Laravel 10+ 强制要求） -
php -m里要看到openssl、pdo、mbstring、tokenizer、xml—— 少一个，composer install就会中断 -
which composer要返回路径，不是 “command not found” -
git --version≥ 2.20（旧版 Git 在 clone Laravel 时可能卡在 submodules）
Mac 用户用 Homebrew 安装： brew install php composer git；Windows 推荐直接用 Laravel Installer（composer global require laravel/installer），比手动配 PHP 稳定。
第一次部署时最容易被忽略的 .env 配置项
很多人只改了数据库，却忘了这 3 个关键开关：
-
APP_ENV=production—— 不设这个，config:cache会拒绝执行 -
APP_DEBUG=false—— 设成true会上线暴露完整错误堆栈，有安全风险 -
LOG_CHANNEL=errorlog或stack—— 默认single在某些云环境（如 Serverless）下会写失败，换成errorlog更兼容
别手敲 .env，用命令生成基础模板：cp .env.example .env，再逐行改。改完立刻跑：php artisan key:generate —— 这步失败，后面全崩。
为什么 Nginx 总是 403 或 500？public 目录没配对
Nginx 的 root 必须精确指向 Laravel 的 public 子目录，不是项目根目录。常见错误写法：
- ❌
root /var/www/myapp;→ 指向了项目根，找不到index.php - ✅
root /var/www/myapp/public;→ 正确入口 - 还要加一句：
index index.php;，否则 Nginx 不知道该找哪个文件当首页 - 如果用 Ubuntu + Nginx，默认站点配置在
/etc/nginx/sites-available/default，改完记得：sudo nginx -t && sudo systemctl reload nginx
Apache 用户注意：.htaccess 文件必须存在且启用 mod_rewrite，否则路由全部 404。
Serverless 平台（如腾讯云 SCF）部署要绕开的两个硬限制
Serverless 不是“换台服务器”，它是无状态、只读文件系统，Laravel 默认行为在这里会直接报错：
-
storage和bootstrap/cache目录不可写 → 必须在scf_bootstrap启动脚本里重定向路径，例如：export APP_STORAGE=/tmp/storage，并在config/filesystems.php中对应修改local磁盘的root -
artisan命令不能直接运行 → 所有缓存命令（config:cache、route:cache）必须在本地执行完再上传，否则上线后首次请求会卡住甚至超时
Serverless 上没有 php-fpm 进程常驻，Laravel 是靠每次 HTTP 请求触发一次启动 —— 所以缓存必须提前 baked in，不能靠运行时生成。
