composer install执行前必须确认三件事：项目根目录存在composer.json和composer.lock；PHP版本与lock文件中记录的兼容；网络能稳定访问镜像源。

composer install 执行前必须确认的三件事

它不是“运行就完事”的命令，卡住、报错、装错版本几乎都源于前期疏漏。

• 项目根目录下存在 composer.json 和 composer.lock —— 缺 composer.lock 时，composer install 会退化为 composer update 行为，导致版本漂移
• PHP 版本与 composer.lock 中记录的兼容 —— 比如 lock 文件里锁的是 "php": "^7.4"，而你本地是 PHP 8.2，就会触发 Your requirements could not be resolved
• 网络能稳定访问镜像源 —— 默认走 packagist.org，国内大概率卡在 Loading composer repositories，不是命令问题，是 DNS 或 CDN 超时

如何正确执行 composer install

别跳步骤，尤其别在 CI/CD 或线上环境手抖敲 composer update。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 确保当前在项目根目录（即有 composer.json 的地方），运行：composer install
• 首次安装或换 PHP 版本后，加 --no-cache 参数避免读取损坏的本地缓存：composer install --no-cache
• 若提示 composer.lock 与 composer.json 不一致（比如有人改了 json 但没提交 lock），先问清楚是否要同步 —— 多数情况下应运行 composer update --lock 仅更新 lock 文件，不下载包
• 安装完成后，检查 vendor/ 目录是否生成，且 vendor/autoload.php 可被正常引入

常见报错及对应解法

报错信息直接指向具体原因，别猜，看字面。

• Your requirements could not be resolved：不是依赖写错了，而是当前 PHP 版本 / 已启用扩展 / lock 文件版本三者冲突。优先执行 composer why-not php:8.2（替换为你实际的 PHP 版本）查阻塞点
• Failed to decode response: zlib_decode(): data error：镜像源返回了损坏响应，立刻切阿里云镜像：composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/
• 安装后类找不到：确认代码中是否写了 require_once 'vendor/autoload.php'，路径必须相对于当前脚本位置；不要用 include 替代 require_once，后者才能保证自动加载注册一次

为什么线上部署必须用 composer install 而不是 update

因为 composer.lock 是契约，不是草稿。

• composer install 严格按 lock 文件安装 —— 同一 commit + 同一 lock = 完全一致的 vendor 目录
• composer update 会重算依赖树、升级次要版本、生成新 lock —— 开发阶段可用，但一旦合入主干，队友或 CI 再跑 install 就可能装出不同版本
• Docker 构建时如果用了 update，镜像层会因依赖变动失效，缓存命中率暴跌；用 install 才能稳定复用 vendor 层

真正容易被忽略的，是 composer.lock 文件本身——它不显眼，但删了或没提交，整个依赖一致性就垮了。团队协作里，它比 composer.json 还重要。