composer install 不会自动切分支，因为它只读取 composer.lock 中锁定的精确版本（含 commit hash 或 tag），完全忽略 composer.json 中声明的分支名；若要切换分支，需修改 composer.json 版本约束后执行 composer install --no-lock 或使用 composer require/vendor update 命令配合 --with-dependencies。
为什么 composer install 不会自动切分支？
因为 composer install 只读取当前项目根目录下的 composer.lock 文件，还原其中记录的精确版本（含 commit hash 或 tag），完全忽略 composer.json 里写的分支名（如 "dev-main" 或 "dev-feature/x"）。你改了 composer.json 里的分支，不删 lock 文件或不运行 composer update，composer install 就当没看见。
composer install 能否直接指定分支安装？
不能。它没有 --with-branch 这类参数。但你可以绕过 lock 文件强制走“更新逻辑”：用 composer install --no-lock + 修改 composer.json 中的版本约束，就能让 Composer 拉取目标分支的最新提交。
- 先修改
composer.json对应包的版本字段，例如："vendor/package": "dev-main"→"vendor/package": "dev-feature/login-ui" - 运行
composer install --no-lock—— 它会忽略现有composer.lock，按新约束解析依赖并生成新 lock - 如果该分支尚未被 Packagist 索引或使用私有仓库，确保已配置
repositories，否则会报Could not find package vendor/package
切换分支时 composer.lock 怎么处理才安全？
直接删 composer.lock 再 install 风险很大：所有依赖都会重新解析，可能引发间接依赖版本漂移。更稳妥的做法是只更新目标包：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 用
composer require vendor/package:dev-feature/x --update-with-dependencies，它会局部更新该包及其兼容的子依赖 - 或运行
composer update vendor/package --with-dependencies，比全量update更可控 - 注意：如果目标分支包含破坏性变更（如函数签名改动），仅靠 Composer 不会校验 PHP 层兼容性，需配合静态分析或测试覆盖
私有 Git 分支依赖常见报错及修复
当你在 repositories 中声明了 type: "vcs" 并指向 Git 仓库，却遇到 Failed to download vendor/package: No valid composer.json found，大概率是分支上缺少 composer.json 或文件权限/路径不对。
- 确认目标分支根目录存在有效的
composer.json（不是空文件，且name字段与require中一致） - 若用 SSH URL（如
git@github.com:org/repo.git），检查本地 SSH key 是否已添加到 GitHub/GitLab，且能git clone成功 - 临时调试可加
-vvv参数：运行composer update vendor/package -vvv，看日志里实际 fetch 的 URL 和响应头
分支切换本质是版本约束变更，关键不在命令本身，而在你是否同步更新了约束、lock 文件和仓库可达性。漏掉任意一环，install 就只是“假装切换”了。
