直接用 composer require 是添加依赖的唯一安全路径，手动改 composer.json 易出错；必须在项目根目录执行，否则会创建新配置；版本号需显式指定，开发依赖加 --dev，装完需验证 autoload 和 lock 文件一致性。
直接用 composer require 就行，别绕弯子——它才是添加新依赖的唯一安全路径，手动改 composer.json 再跑 install 或 update 容易漏步骤、写错约束、导致本地能跑线上炸。
执行前必须确认在项目根目录
命令报 Could not find a composer.json file 或静默创建新 composer.json，基本就是当前目录错了。不是“有没有 JSON 文件”，而是“是不是你项目的根目录”。
- 用
pwd（macOS/Linux）或cd（Windows）看当前路径，确保能看到composer.json - 常见踩坑点：人在
src/、app/或tests/里直接敲命令，结果在子目录生成了全新配置 - CI 脚本里建议加检查：
test -f composer.json || { echo "No composer.json"; exit 1; }
版本号不写就等于开盲盒
不带版本号运行 composer require monolog/monolog，Composer 会按 minimum-stability 和平台限制（比如 "php": "7.4"）选一个“最新稳定版”，但这个“最新”可能跳到 v3，而你的代码只适配 v2。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 生产环境推荐显式写约束：
composer require monolog/monolog:^2.10（允许 2.10.x → 2.99.x，不跨 3.0） - 想锁死精确版本（如压测复现）：
composer require monolog/monolog:2.10.0 - 别写
2.10.*——Composer 已弃用通配符语法，会被当字面量处理，大概率报错 - 查可用版本：
composer show monolog/monolog --all
dev 依赖不加 --dev 就会打进生产环境
装 PHPUnit、PHPStan、CS-Fixer 这类工具，如果漏了 --dev，它们会进 require 字段，上线时被 composer install --no-dev 跳过，结果代码里 use PHPUnitFrameworkTestCase 直接报错。
- 开发工具一律加
--dev：composer require --dev phpunit/phpunit:^10 - 运行时必需的包（如
guzzlehttp/guzzle、symfony/http-client）不加--dev - 部署命令必须带
--no-dev，否则 CI 构建和线上行为不一致
装完类还是找不到？先看 autoload 和 lock 是否同步
vendor 目录里明明有文件，new VendorPackageClass() 却报 Class not found，90% 是自动加载没注册或 composer.lock 滞后。
- 确认该包的
composer.json有autoload字段（如"psr-4": {"Monolog\": "src/"}） - 确认项目入口已
require 'vendor/autoload.php'，不是漏写、路径错或条件未覆盖 - 运行
composer dump-autoload强制刷新映射（尤其改过自己项目的autoload段后） - 如果
composer.lock和composer.json不一致，先composer install看报错提示，再决定是否composer update vendor/name
最常被忽略的是：装完包后不验证 vendor/autoload.php 是否真包含该命名空间，以及误把 composer.lock 当缓存删掉——它一旦损坏，CI 构建就会和本地彻底脱钩。
