PHP自动化部署脚本教程：Deployer一键上线指南

Deployer虽号称“一键部署”，实则暗藏诸多易被忽视的陷阱：从SSH用户权限与目标目录组写入权限不匹配导致的deploy:prepare失败，到忽略显式调用deploy:vendors致使vendor/autoload.php缺失引发500错误；从本地.gitignore的.env如何安全、可靠地同步至线上并确保环境变量即时生效，到rsync未排除node_modules等冗余文件造成的巨幅传输延迟——每个环节都直指PHP工程师对Linux权限体系、Composer执行时机、环境隔离机制及远程运维真实细节的深度理解，稍有疏漏便可能让一次本该流畅的上线演变成深夜紧急救火。

Deployer 部署失败时 deploy:prepare 报错 Permission denied

这是最常卡住的第一步：Deployer 尝试在远程服务器上创建部署目录，但当前 SSH 用户没权限写入目标路径（比如 /var/www/myapp）。不是 Deployer 本身有问题，而是 Linux 文件权限和用户组没对齐。

• 确认远程用户（如 deploy）属于目标目录所属组，例如执行 sudo usermod -aG www-data deploy
• 目标目录需提前存在且组可写：sudo chgrp www-data /var/www/myapp && sudo chmod g+rwx /var/www/myapp
• 别依赖 sudo 自动提权 —— Deployer 默认不走 sudo，也不建议在 deploy.php 里硬加 sudo 命令，容易引发权限混乱
• 检查 dep deploy 执行时用的 SSH 用户是否和你手动登录的一致（ssh deploy@host 能否成功 cd 进目标目录）

PHP 项目部署后 vendor/autoload.php 找不到

Deployer 默认只 rsync 项目源码，不自动运行 composer install。很多新手以为“上传完就完事了”，结果线上直接 500。

• 必须显式声明 composer 任务，在 deploy.php 中加入：after('deploy:failed', 'deploy:unlock'); 后补上 after('deploy:symlink', 'deploy:vendors');
• deploy:vendors 是 Deployer 内置任务，但它默认调用的是 composer install --no-dev --quiet --optimize-autoloader；如果你用了自定义 composer 路径或需要 --with-all-dependencies，得重写这个 task
• 确保远程服务器已安装 Composer，并且 which composer 能返回路径（常见坑：用 curl -sS https://getcomposer.org/installer | php 装在用户目录下，没加进 $PATH）

如何让 Deployer 正确加载 .env 文件而不提交到仓库

本地 .env 不能进 Git，但线上又必须有 —— Deployer 不会自动帮你传或生成，得自己接管。

• 别把 .env 放在共享目录（shared）里就以为万事大吉：Laravel 的 env() 在首次加载后会缓存值，重启 PHP-FPM 或 OpCache 才生效，部署时改了可能不立即起效
• 推荐做法：在 deploy.php 中用 upload() 上传预配置好的 .env.production 到远程，再在 deploy:symlink 前用 run("ln -sf {{release_path}}/.env.production {{release_path}}/.env")
• 更稳妥的是用 run("cp {{shared_path}}/.env {{release_path}}/.env")，前提是先确保 {{shared_path}}/.env 已存在且权限正确（600，属主为 web 用户）

为什么 dep deploy 慢得像在编译 Linux 内核

Deployer 默认启用 rsync，但若没配排除规则，会把 node_modules、.git、storage/logs 全拖过去，一次部署几百 MB 往上走。

• 务必在 deploy.php 中配置 set('rsync_exclude', ['.git', 'node_modules', 'storage/logs', 'storage/debugbar', 'tests']);
• 如果项目用 Docker，别用 Deployer 推代码 —— 改用构建镜像 + docker stack deploy，Deployer 在这种场景下纯属添乱
• SSH 连接慢？加 set('default_timeout', 300); 防超时，同时检查远程服务器是否启用了 GSSAPIAuthentication yes（OpenSSH 默认开启，内网有时反而拖慢连接，可关掉）

Deployer 看似一键，但每个环节都依赖你对远程环境、PHP 运行上下文和 Composer 生命周期的真实理解。漏掉一个 shared 目录的权限，或少写一行 rsync_exclude，就可能让上线变成深夜救火。

到这里，我们也就讲完了《PHP自动化部署脚本教程：Deployer一键上线指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！