如何详细实现Laravel部署环境间的切换？

本文共计1174个文字，预计阅读时间需要5分钟。

环境切换的本质是控制 + `APP_ENV` 和 + `APP_DEBUG` 这两个核心配置，但直接修改 + `.env` + 文件在部署中极易出错——例如Git误提交、多环境覆盖、权限问题等导致读取失败。

正确做法是绕过 .env，用服务器环境变量接管：

• APP_ENV=production 必须设为 production，否则 Laravel 不会启用缓存配置、路由、视图，性能直接受损
• APP_DEBUG=true 在生产环境绝对禁止，不仅暴露敏感路径和 DB 信息，还可能触发异常堆栈写入日志引发磁盘爆满
• Nginx/Apache 中通过 fastcgi_param 或 SetEnv 注入，比依赖 .env 更可靠；Docker 则用 environment: 块声明
• 验证是否生效：执行 php artisan tinker 后输入 app()->environment() 和 config('app.debug')，结果必须分别是 "production" 和 false

为什么 php artisan config:cache 在部署后必须运行

开发时 Laravel 每次请求都重新加载 config/*.php，但生产环境不 cache 就等于裸奔：配置解析开销大、无法利用 OPCache 预编译优势、甚至某些扩展（如 Horizon）启动直接报错。

常见错误现象：php artisan config:cache 执行失败，提示 “Class not found” 或 “Cannot redeclare function”，根本原因是缓存前没清掉旧的 bootstrap/cache/config.php，或代码里有动态 require 配置文件。

• 部署脚本中务必按顺序执行：php artisan config:clear → php artisan config:cache
• 确保所有配置值都是“可序列化”的：不能含闭包、resource、stdClass 实例；env() 调用必须只出现在 config/*.php 中，且不能嵌套在条件语句外层
• 如果用了自定义配置文件（如 config/services.php），检查它是否被 config:cache 自动包含——默认只扫描 config/ 下 PHP 文件，不含子目录

不同部署方式下 .env 的处理差异

.env 文件不是“部署产物”，而是环境描述符。它的存在位置、读取时机、是否提交到仓库，取决于部署链路设计。

• 传统 FTP/SFTP 部署：把 .env 放在 /var/www/html/ 根目录，但必须确保 Web 服务器禁止访问（Nginx 加 location ~ /\.env { deny all; }）
• Git-based 部署（如 Envoyer）：.env 存在共享目录（如 /var/www/myapp/shared/.env），每次发布软链接过去，避免每次覆盖
• Docker 部署：绝不在镜像里 COPY .env，改用 docker run --env-file 或 docker-compose.yml 的 environment: 字段注入；镜像内只保留 .env.example
• CI/CD 流水线（如 GitHub Actions）：用 secrets 注入环境变量，再生成临时 .env 写入构建上下文，构建完立即删掉，不落盘

APP_KEY 不同步会导致什么问题

APP_KEY 是 Laravel 加密、Session、Cookie、Signed URL 的根基。部署时若新实例用默认 key 或空 key，用户登录态全丢、密码重置链接失效、队列任务解密失败——而且这些错误往往不报异常，只静默失败。

• 错误现象包括：InvalidSignatureException、Session 无法持久化、Redis 中的 laravel_database_session:xxx 值为空或乱码
• 必须在首次部署前就生成唯一 APP_KEY（用 php artisan key:generate --show），并统一注入所有节点；不能每个实例自己生成
• Key 一旦上线就不能再改，除非你愿意让用户全部重新登录、废弃所有已签名 URL、清空全部 Session 存储
• 检查方式：对比不同服务器上 php artisan tinker 中的 config('app.key') 输出是否完全一致（注意长度：Laravel 9+ 要求 32 字符 AES-256）

环境变量看似简单，但 Laravel 的缓存机制、加密依赖、配置加载顺序会让小疏忽变成线上事故。最常被忽略的是：APP_KEY 必须跨实例一致，而 config:cache 必须在所有环境变量就位后再执行——这两点卡住的人最多。