新项目上必须执行的 composer install 步骤

正确的姿势其实很清晰：只把 composer.json 和 composer.lock 这两个文件传到新项目的根目录，然后执行下面这条命令：

rm -rf vendor/
composer install --no-dev --optimize-autoloader

这里有几个参数值得细说：

• --no-dev：这个参数会跳过 require-dev 部分定义的开发依赖（比如 phpunit）。在生产环境，这能避免不必要的测试入口暴露，减少潜在的攻击面。
• --optimize-autoloader：它会生成一个静态的类映射文件，替代 Composer 默认的动态查找。对于 Lara vel、Symfony 这类包含大量类文件的大型框架来说，这能显著减少 file_exists() 的系统调用，提升自动加载速度。
• 慎用绕过检查：别图省事加上 --ignore-platform-reqs，它只是掩耳盗铃，跳过了环境检查，实际问题还在。如果真有临时需求，也最多用 --ignore-platform-req=php 针对特定项，并且务必确认代码确实能正常运行。
• 内存不足怎么办：如果安装过程中报出 Allowed memory size exhausted 错误，可以尝试用这个命令来解除内存限制：php -d memory_limit=-1 $(which composer) install。

常见失败原因和快速定位方法

如果 composer install 卡住了或者报错了，别慌。优先按以下顺序排查：

• 核对 PHP 版本：先用 php -v 看看版本号是否满足 composer.json 里 "php": "^8.1" 这类要求。更精确的方法是，在原来的服务器上运行 composer show php，看看 Composer 实际解析出的版本约束是什么。
• 检查扩展依赖：运行 composer check-platform-reqs，它能清晰地列出所有缺失的系统扩展（比如 mbstring、xml）。缺什么就装什么，CentOS 系用 yum install，Debian/Ubuntu 系用 apt install。
• 确认 lock 文件存在：检查一下 composer.lock 是不是被 .gitignore 忽略了，或者压根没提交。这个文件必须存在，否则 install 命令会退化成 update，去拉取依赖包的最新版本，很可能导致兼容性断裂。
• 配置私有仓库认证：如果依赖了私有包（比如公司内部的 GitLab 仓库），需要提前配置好认证信息：composer config -g http-basic.gitlab.example.com token username。

Composer 1.x 迁移到 2.x 的特殊处理

这是一个容易踩坑的升级场景。如果旧项目用的是 Composer 1，而新服务器装的是 Composer 2，那么旧的 composer.lock 文件是不能直接复用的。

• 重建依赖：最稳妥的办法是，先删除旧的 composer.lock 和 vendor/ 目录，然后直接运行 composer install。Composer 2 会生成新的 lock 文件格式（里面会包含 "lock-version": 2 这样的标识）。
• CI/CD 流水线适配：如果在持续集成流程中混用了 v1 和 v2，可以在脚本里加个判断，例如用 grep -q '"lock-version": 2' composer.lock 来检测，如果匹配就强制使用 composer2 命令。
• 并行安装而非全局升级：全局升级 Composer 版本风险较高。可以考虑用 curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer2 单独安装一个 Composer 2 的可执行文件，这样不会影响原有的、基于 v1 的流程。
• 注意插件兼容性：项目里如果有自定义的 Composer 插件脚本（比如挂钩到 post-autoload-dump 事件），这些脚本很可能在 v2 下失效，因为内部 API 已经重构了，需要逐个测试验证。

最后，也是最容易被忽略的一点：迁移完成后，别以为 composer install 成功执行就万事大吉了。一定要跑一次实际的业务请求，或者执行一个 CLI 命令（比如 php artisan tinker 或 php index.php），亲眼确认自动加载机制真正生效，类能够被正常实例化。很多深层问题，往往只在运行时才会暴露出来。