执行 composer install 前必须确认存在 composer.lock 文件，否则行为等同于 composer update，导致本地与线上不一致；报“Could not find a composer.json file”是路径错误或文件缺失所致，需用 pwd 和 ls -la 验证当前目录下真实存在该文件。

别急着敲 composer install，先确认你有没有 composer.lock 文件——没有它，composer install 就会退化成 composer update，本地和线上行为不一致是高频翻车点。

为什么执行 composer install 却报错“Could not find a composer.json file”

这是路径或文件缺失导致的硬性失败，不是网络或权限问题。

• 检查当前目录下是否存在 composer.json（注意大小写，不能是 Composer.json 或 composer.JSON）
• 用 ls -la（Linux/macOS）或 dir（Windows）确认文件真实存在，别只靠资源管理器“看着有”
• 常见误操作：在父目录运行命令，但 composer.json 其实放在子文件夹里；解决办法是先 cd 进目标文件夹再执行
• 如果项目是从 Git 克隆的，确认是否漏掉了 .gitignore 里被忽略的 composer.json（极少见，但有人手动删过）

执行 composer install 卡住、超时或提示 “Connection timed out”

默认源在国外，国内直连基本不可用，这不是你网络差，是源本身不可达。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 必须配国内镜像——阿里云镜像最稳：composer config -g repo.packagist https://mirrors.aliyun.com/composer/
• 验证是否生效：运行 composer config -g repo.packagist，输出应为阿里云地址
• 如果已配镜像仍卡住，大概率是 DNS 污染或本地代理干扰；临时关闭代理，或加 -vvv 参数看具体卡在哪一步（比如卡在 Downloading https://mirrors.aliyun.com/... 就说明镜像没生效）
• Mac/Linux 用户若用 Homebrew 装的 PHP，有时 composer 命令实际调用的是旧版 PHP，导致 OpenSSL 扩展不可用——用 which composer 和 composer --version 确认 PHP 版本是否匹配

composer install 后 vendor 目录为空或报错 “Your requirements could not be resolved”

这不是下载失败，而是依赖冲突，核心在 composer.lock 和 composer.json 的版本约束不兼容。

• 先看错误里提到的具体包名，比如 guzzlehttp/guzzle，再查这个包在 composer.lock 中锁定的版本和 composer.json 中声明的版本范围是否打架
• 新手最容易踩的坑：在已有项目里乱跑 composer require xxx，结果改了 composer.json 却没更新 composer.lock，导致 install 时两边对不上
• 安全做法：协作项目中，只允许 composer install；新增依赖必须由负责人跑 composer update xxx 并提交新的 composer.lock
• 实在搞不定，临时方案是删掉 composer.lock 再跑 composer install（仅限本地调试，禁止提交）——这等于放弃版本锁定，风险自担

最常被忽略的一点：composer install 不会自动创建 vendor/autoload.php，但它依赖这个文件被正确引入。如果你用 require 'vendor/autoload.php' 报错，先检查 vendor 目录是否存在、是否可读，再确认 PHP 是否启用了 allow_url_include（某些共享主机默认关闭，需联系运维开启）。