composer.json是项目依赖契约而非配置文件，改错字段会导致依赖树错误或class not found；require/require-dev需严格区分运行与开发依赖，autoload须匹配命名空间、路径及文件结构，install依赖lock文件还原环境，update则重新解析版本约束。

composer.json 不是“可有可无的配置文件”，它是整个 Composer 项目的行为契约——改错一个字段，composer install 就可能装出完全不同的依赖树，甚至直接报 Class not found 或 PHP Fatal error。

它不负责“怎么装”，而是明确声明“要装什么、怎么加载、在什么环境下装”。下面说几个最常踩坑的关键点。

require 和 require-dev 放错位置，上线就炸

这两个字段决定哪些包会进生产环境：

• require 里的包，在 composer install --no-dev 下仍会被安装；缺它，代码运行时直接报错
• require-dev 里的包（比如 phpunit/phpunit、php-cs-fixer/php-cs-fixer）默认被跳过
• 常见错误：把 symfony/console 塞进 require-dev，结果 bin/console 在生产环境跑不起来——因为它实际被入口脚本调用了
• 别用 "*" 或 "dev-main" 写进 require，稳定性不可控；minimum-stability 默认是 stable，但若没显式设 prefer-stable: true，仍可能装到 -beta 版本

autoload 配错，类永远找不到

psr-4 是现代 PHP 项目唯一推荐的自动加载方式，但它对三者严格一一对应：

Workflow Decomposer

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

下载

• 命名空间（如 "App\"）
• 路径（如 "src/"）
• 文件物理结构（src/Http/Controller.php 必须以 namespace AppHttpController; 开头）
• 路径末尾不加 / 会静默失败；命名空间末尾少写反斜杠（"App" 而不是 "App\"）会导致 JSON 解析失败
• 改完 autoload 后必须手动执行 composer dump-autoload，否则 vendor/composer/autoload_psr4.php 不更新，类依然找不到

composer install vs composer update，行为根本不同

核心区别在于是否读取 composer.lock：

• composer install：优先看 composer.lock，按里面锁定的精确版本还原整个 vendor/；没有 lock 文件才退回到 composer.json 解析
• composer update：完全忽略 composer.lock，重新解析 composer.json 中的版本约束，找最新兼容版本，再重写 composer.lock
• 协作开发中，composer.lock 必须提交进 Git；CI 构建环境应始终用 composer install，而不是 update，否则不同时间构建结果可能不一致

repositories 和 config.platform 不是高级选项，而是部署底线

镜像源和平台模拟直接影响依赖能否装上、装得对不对：

• repositories 可用于切换国内镜像（如 https://packagist.phpcomposer.com），避免因网络问题导致安装失败
• config.platform 可模拟目标环境（比如线上是 PHP 8.1，本地是 8.3），防止装入不兼容的扩展或版本
• 不配 platform，composer install 可能选错依赖版本，上线后才发现扩展缺失或函数不存在

最容易被忽略的是：改了 composer.json 后，很多人只记得 composer install，却忘了 dump-autoload 或检查 composer.lock 是否同步。这些步骤不是“可选”，而是行为生效的必要条件。