生产环境部署失败主因是忽略隐性依赖：需检查.env配置与Git隔离、APP_KEY重生成、缓存命令前置验证、排除开发文件、静态资源完整性、storage/bootstrap/cache权限及日志磁盘空间。
直接打包 Laravel 项目代码本身不难，但生产环境部署失败，90% 出在「没做对检查」——不是缺命令，而是漏了环境、权限、缓存、配置这些隐性依赖。
确认 .env 已正确配置且未提交到 Git
Laravel 启动时优先读取 .env，但很多团队会误把开发配置留在生产机上，或忘记重命名示例文件。
- 检查线上服务器是否存在
.env，内容是否含APP_ENV=production和APP_DEBUG=false - 确认
.env不在 Git 历史中：git ls-files | grep .env应无输出；若曾误提交，需用git filter-repo清理 -
APP_KEY必须通过php artisan key:generate生成，不能复用开发环境的值（否则加密/Session 失效）
运行 php artisan config:cache 和 php artisan route:cache 前先验证
这两条命令能提速，但一旦出错会导致整个应用 500 —— 尤其当配置里用了闭包、动态变量或未加载的服务提供者时。
- 先执行
php artisan config:clear和php artisan cache:clear清旧缓存 - 再试运行
php artisan config:test（Laravel 10.28+）或手动检查config/*.php中是否含env()调用（缓存后不生效，应改用config('app.name')等间接方式） -
route:cache不支持闭包路由，检查routes/web.php和routes/api.php是否全为数组式定义
打包时排除开发专用文件和目录
用 zip 或 tar 直接压缩整个项目根目录，极大概率带入危险项。
- 必须排除：
node_modules/、vendor/（应走composer install --no-dev --optimize-autoloader）、.git/、.env.example、tests/、phpunit.xml - 推荐用
composer install --no-dev --optimize-autoloader安装依赖，而非复制本地vendor（版本/扩展差异易引发报错） - 静态资源如
public/mix-manifest.json必须存在，否则@vite或mix()辅助函数会返回空 URL
Web 服务器权限与 storage / bootstrap/cache 可写性
Nginx/Apache 进程用户（如 www-data 或 nginx）必须能写入这两个目录，否则日志写不进、视图编译失败、队列监听崩溃。
- 运行：
chown -R www-data:www-data storage bootstrap/cache（根据实际 Web 用户调整） - 设置权限：
chmod -R 755 storage bootstrap/cache（不建议 777） - 验证：用 Web 用户执行
sudo -u www-data touch storage/test.txt，无报错即 OK - 若用 Docker，注意挂载卷的 UID/GID 是否匹配容器内用户
最常被跳过的其实是 storage/logs/ 的磁盘空间和轮转配置——某次部署后日志暴涨占满磁盘，结果连错误都看不到。别只盯着代码打包，环境里的“静默依赖”才最要命。
