项目初始化时 composer install 报错，八成是 composer.lock 缺失或环境不匹配，导致 fallback 为 composer update 行为；需先确认 composer.lock 是否存在且非空，再检查 PHP 版本、扩展、platform 配置及证书等环境前提。
项目初始化时 composer install 报错，八成不是网络慢、不是 PHP 坏，而是 composer.lock 缺失或环境不匹配——它根本没走“安装”，而是 fallback 成了 composer update 行为，结果不可控。
刚 clone 下来就报错？先确认 composer.lock 是否真实存在
很多团队交付代码时漏提交 composer.lock，或者 .gitignore 里误加了 /composer.lock。没有它，composer install 就会退化为求解依赖，触发版本冲突、PHP 版本校验失败等一连串问题。
- 运行
ls -la composer.lock，确认文件存在且非空（大小 > 0） - 如果不存在，别急着
composer update—— 先问清楚：这个项目是否允许你决定依赖版本？生产环境严禁擅自更新 - 若确需生成 lock 文件，用
composer update --dry-run预览变更，再决定是否执行
Your requirements could not be resolved 真实原因不是“冲突”，是本地 PHP 或扩展不达标
这个错误常被误读为包版本打架，其实 Composer 已经拿到所有元数据，卡在“本地环境无法满足 lock 文件里某包的运行前提”。
- 运行
php -v和php -m | grep -E "mbstring|openssl|curl|json"，确认 CLI 模式下 PHP 版本和关键扩展真实可用（Web SAPI 和 CLI 的 php.ini 可能不同） - 检查
composer.json顶部是否有"config": {"platform": {"php": "8.2.10"}}这类硬编码；如果实际是 PHP 8.1，它就会直接拒绝，哪怕包本身兼容 - 用
composer check-platform-reqs直接列出所有缺失项，比猜更快
换源后仍卡在 Loading composer repositories？别只盯镜像配置
镜像只加速包拉取，不解决底层证书或缓存污染。国内用户遇到这问题，90% 是 CA 证书过期或旧失败记录残留。
- 先清缓存：
composer clear-cache—— 不清它，换十次源都一样卡 - 验证 PHP 的证书路径：
php --ini找到加载的php.ini，检查curl.cainfo和openssl.cafile是否指向有效证书（推荐从 https://www.php.cn/link/5fe4dadcdb001d8566cd20e6d8a20251 下载最新版） - 如果企业内网走代理，补上：
composer config -g http-proxy http://10.0.1.100:8080；某些防火墙拦截 SNI，可临时关 TLS 校验：composer config -g secure-http false（仅限开发机）
权限报 Permission denied？别 chmod -R 777，先查属主
根本不是权限位问题，而是 vendor/、composer.lock 或 ~/.composer/cache/ 被 root 占了——尤其常见于宝塔、Docker 或误用 sudo composer install 后。
- 三步定位：
ls -ld vendor/ composer.lock、composer config --global cache-dir、whoami - 如果输出里含
root，就用sudo chown -R $USER:$USER vendor/ composer.lock和sudo chown -R $USER:$USER $(composer config --global cache-dir) - 切记：不要
sudo composer install。一旦 vendor/ 下混入 root 所有子目录，后续composer update可能只失败一半，chown -R都救不回来，只能删 vendor/ 重来
最常被忽略的一点：报错停在 composer install 阶段，不代表问题出在安装过程本身——可能是 composer.json 里包名多了一个空格、repositories 字段格式写错、甚至 Git 拉下来的文件权限被破坏。别跳过 ls -la 和 cat composer.json | python3 -m json.tool 这种基础验证。
