直接能跑通的laravel github actions部署流程核心三点：php环境须显式声明、composer install需加--ignore-platform-req=ext-*跳过平台限制、远程部署脚本必须幂等且含php artisan down/up维护模式控制；其余配置中小项目90%无需。
直接能跑通的 Laravel GitHub Actions 部署流程，核心就三点：PHP 环境必须显式声明、composer install 要跳过平台限制、远程部署命令必须幂等且带维护模式控制。其他花哨配置，90% 的中小项目用不上。
为什么 composer install 总卡住或报错？
GitHub 默认 runner 的 PHP 版本（常为 8.3 或 8.4）和扩展往往不满足 composer.json 中 "platform" 声明，或缺 ext-pdo_mysql、ext-xml 等 Laravel 强依赖扩展。
- 必须用
shivammathur/setup-php@v2显式安装对应版本，比如php-version: '8.2'，并列出所有必需扩展：mbstring, dom, xml, curl, pdo, pdo_mysql, opcache -
composer install加上--ignore-platform-req=ext-*，否则 CI 会因扩展缺失直接失败 - 生产环境务必加
--no-dev --optimize-autoloader，避免 dev 包污染和 autoloader 性能损耗
如何让部署脚本真正“零停机”？
直接 git pull && php artisan migrate 是最常见错误——迁移失败或构建中断时，线上服务就挂了。真正在用的方案是软链接切换 + 维护模式兜底。
- 服务器上按时间戳或 commit hash 建独立部署目录，如
/var/www/myapp/releases/202607081522 - 部署脚本里先
cd到新目录，执行composer install、php artisan migrate --force、npm run prod，全部成功后再改current软链接指向它 - 每次部署开头加
php artisan down --render="maintenance"，结尾加php artisan up；即使中间出错，用户也只会看到维护页，不会看到 500 - 别在 GitHub Actions 里写一堆
ssh命令拼接，把完整部署逻辑封装成.scripts/deploy.sh放进仓库，Actions 只负责传文件+执行它
appleboy/ssh-action 连不上或权限被拒？
这不是网络问题，99% 是密钥或用户权限配置不对。GitHub Secrets 里存的 SSH_PRIVATE_KEY 必须是未加密、无换行符的纯文本私钥（可用 cat ~/.ssh/id_rsa | tr -d '\n' 检查），且目标服务器的 sshd_config 必须允许该用户使用密钥登录。
- 服务器端确认
~/.ssh/authorized_keys里已追加对应公钥，且chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys - Actions 中
username必须和服务器上实际拥有项目目录权限的用户一致（通常是www-data或deploy，不是root） - 如果用
sudo执行命令（如systemctl reload nginx），需提前在/etc/sudoers里给该用户免密权限，否则卡死 - 别用
appleboy/ssh-action@master—— 它已废弃，固定用@v0.1.7或更高稳定版
最易被忽略的一点：所有敏感值（APP_KEY、DB_PASSWORD、REDIS_PASSWORD）必须通过 ${{ secrets.XXX }} 注入，绝不能硬编码在 .env 文件或 workflow YAML 里；哪怕只是测试环境，泄露一个 APP_KEY 就等于交出整个 session 解密能力。
