Composer 本身不提供部署能力，仅是依赖管理器；所谓自动化部署实为通过 scripts 字段串联命令，并配合环境、权限与路径控制来模拟部署动作。
这里有个常见的误解需要先澄清：Composer 本质上是一个依赖管理器，它并不内置“部署”功能。我们常说的“Composer自动化部署”，其核心原理其实是用 composer.json 里的 scripts 字段，把一连串命令像糖葫芦一样串起来，再通过精准的环境配置、权限管理和路径控制，来模拟出部署的流程。直接写个 "deploy": "rsync ..." 看似简单，却很容易在生产环境栽跟头。真正的门道在于，你得清楚哪些步骤必须拆开，哪些关键参数一个都不能省。
composer.json 的 scripts 不是万能胶水
不少开发者喜欢把所有的部署操作一股脑塞进一个 deploy 脚本里，结果一执行，不是卡在 php artisan migrate 的交互提示上，就是遇到 rsync 权限拒绝。这里的关键在于理解：scripts 本质上是一个按顺序执行的 shell 命令列表，它本身没有错误中断机制（除非你手动加上 &&），更谈不上什么上下文隔离。
- 切忌写成
"deploy": "git pull && composer install && rsync ..."这种形式——万一 git 拉取失败，后面的命令依然会继续执行，后果难以预料。 - 对于数据库迁移这类敏感操作，必须显式加上
--force标志或做好前置检查，否则脚本会被交互式提示卡住，部署流程就此中断。 - 要特别注意，
post-install-cmd和post-update-cmd这类事件脚本是在本地运行 Composer 命令时触发的。别指望代码 push 到仓库后，线上服务器会自动执行这些缓存清理命令。 - 脚本中调用的
php或artisan命令，路径必须明确。比如使用./artisan而不是模糊的php artisan，这能有效避免因系统默认 PHP 版本不一致而引发的问题。
怎么安全地组合 deploy:prepare / deploy:sync / deploy:activate
一个稳健的策略是把部署流程拆分成清晰的阶段，比如 deploy:prepare、deploy:sync、deploy:activate。这样做不仅出了问题能快速定位，也方便 CI/CD 系统分步骤调用。核心原则是：每个阶段只专注一件事，一旦失败就立刻停止。
deploy:prepare（准备阶段）：负责拉取代码、安装 Composer 依赖、构建前端资源（如执行npm run build），并清理不必要的临时文件。deploy:sync（同步阶段）：使用类似rsync -a vz --delete --exclude=".git" ./ user@server:/path/的命令进行文件同步。务必注意--delete参数，它会删除目标目录中存在而源目录中没有的文件，使用前需确认。deploy:activate（激活阶段）：通过 SSH 远程执行命令，例如ssh user@server 'cd /path && php artisan config:cache && chown -R www-data:www-data storage/'，完成缓存、权限设置等收尾工作。- 所有涉及
rsync或ssh的命令，都必须提前配置好 SSH 免密登录，否则脚本会在等待输入密码的地方无限期阻塞。
为什么 vendor 目录不该随 rsync 一起传
把整个项目目录（包括庞大的 vendor/）用 rsync 直接同步到服务器，看起来省事，实则埋下不少隐患：
- 不同服务器间的 PHP 扩展（比如
ext-redis）或 PHP 版本可能存在差异，直接同步的vendor/目录中的某些编译后文件或类库可能无法加载。 vendor/目录体积通常很大，通过网络传输既慢又不稳定，容易因网络波动中断。相比之下，在目标服务器上执行composer install --no-dev --optimize-autoloader往往更快、更可靠。- 如果项目使用了
COMPOSER_VENDOR_DIR环境变量或自定义了安装路径，rsync 同步过去的vendor/目录位置，很可能与 Composer 自动加载器预期寻找的路径不一致，导致致命错误。
因此，正确的做法是在 deploy:sync 步骤之后，通过 SSH 在目标服务器上远程执行 composer install。当然，前提是目标机已经预装好了 Composer 和符合要求的 PHP 环境。
post-deploy 脚本在哪儿真正起作用
需要特别注意的是，post-deploy 这个名称在 Composer 语境下，并不像 Deployer 或 Capistrano 这类专业部署工具中的钩子（hook）那样会自动触发。它仅仅是 composer.json 中一个自定义的脚本名称。只有当你手动运行 composer run post-deploy，或者在另一个脚本里使用 @post-deploy 语法显式调用它时，它才会执行。
- 它不会因为
git push了代码或者 CI 流水线跑完了就自动运行。 - 如果你在使用 Deployer，那么类似
after('deploy:symlink', 'deploy:php')这样的任务才是真正的“部署后”钩子。你的post-deploy脚本，需要在 Deployer 的任务里通过类似run('cd {{release_path}} && {{bin/php}} {{release_path}}/composer.phar run post-deploy')的命令去主动调用。 - 很多团队误以为在
composer.json里写上post-deploy就万事大吉，结果上线后发现缓存没清、目录权限没改——根本原因就是这个脚本从来没人去执行它。
说到底，所有这些自动化脚本都严重依赖目标服务器环境的稳定性。PHP 版本、扩展模块、磁盘空间、SSH 连接超时设置，甚至 /tmp 目录是否可写，任何一个环节出问题，都可能让看似完美的“一键部署”卡在半路。所以，别过分迷信自动化，最稳妥的办法是：在组装你的“一键脚本”之前，先确保每一条命令在目标环境上都能单独顺利执行。
