Composer报“Could not resolve”主因是本地git脏工作区或镜像失效导致远程分支不可达；应先用git ls-remote验证分支，再清理vendor目录、清缓存并检查镜像源配置。
不是分支冲突，是 Composer 在读取本地 git 仓库状态时被脏工作区或错误镜像干扰了——它误判远程分支不可达，进而拒绝更新或报错“Could not resolve package”。
为什么 composer update 报 “Branch conflict” 或 “Could not resolve”
Composer 本身不处理 Git 分支，所谓“分支冲突”其实是它在解析 composer.json 中的 VCS 包（如 "git@github.com:vendor/pkg.git" 或 "https://github.com/vendor/pkg"）时，尝试读取本地 clone 的副本。一旦该副本存在但状态异常，就会触发误报：
- 本地
vendor/pkg目录下 git 工作区有未提交修改、未拉取的远程 commit 或 detached HEAD —— Composer 拒绝覆盖，报错类似Could not resolve dev-main to a commit - 项目配置了私有镜像（如
repositories中 type=package 或 vcs），但镜像地址已失效或返回 404/500 —— Composer 日志里可能只显示Failed to download vendor/pkg，实际卡在元数据获取阶段 - 全局或项目级
composer config --global repo.packagist.org被手动设为非官方源，且该源未同步最新分支信息 —— 导致dev-main、dev-develop等开发分支无法解析
清理本地 VCS 包残留最有效三步
针对 vendor/pkg 目录下因手动 git 操作或中断安装留下的坏状态：
batch-git-url-replace
下载
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
- 进到
vendor/pkg目录，运行git status：若提示not a git repository或detached HEAD，说明已损坏 - 直接删掉整个
vendor/pkg目录（不要只删 .git）—— Composer 下次 install/update 会重新 clone - 执行
composer clear-cache，清掉 Composer 内部缓存的元数据（尤其影响分支解析）
检查并重置镜像源是否可信
镜像问题常被忽略，但它会导致所有包（包括 Packagist 官方包）解析失败：
- 查当前镜像：运行
composer config --list | grep repo，重点关注repo.packagist.org和repositories下的自定义项 - 临时切回官方源验证：执行
composer config --global repo.packagist.org https://packagist.org，再试composer update --dry-run - 若用私有镜像，确认其支持
packages.json接口且未过期（比如镜像未同步dev-main分支的最新 commit hash） - 项目级镜像优先级高于全局，检查
composer.json的repositories字段是否含无效 URL 或 type=package 的硬编码包列表（这种写法极易过期）
遇到 dev 分支解析失败，先别急着改 constraint
报 Could not resolve dev-main to a commit 时，90% 不是版本约束写错了，而是远程分支本身不可见：
- 手动
git ls-remote https://github.com/vendor/pkg.git refs/heads/main（替换为实际 URL），看是否返回 commit hash；如果为空或 403，说明远程库已删分支或设为私有 - Composer 默认只 fetch
refs/heads/*，不 fetchrefs/pull/*或refs/tags/*—— 若你写了"dev-pull/123": "dev-main"这类非常规引用，必须显式加"options": {"ref": "pull/123/head"} - 避免在
require中直接写"vendor/pkg": "dev-main as 1.0.0"：as 别名仅用于版本号映射，不解决分支不可达问题
真正麻烦的不是报错本身，而是它往往混在一堆依赖解析日志里，让人误以为是语义版本冲突；盯住 Could not resolve 后面的分支名和 URL，比翻 composer why-not 更快定位根因。
