需在composer.json中声明VCS仓库并运行composer update --lock；分支名须严格匹配远程refs/heads下的原始名称；dev分支需加@dev后缀或配置branch-alias；类找不到是autoload未生效，需检查PSR-4配置、路径和命名空间一致性。
dev分支写对了但还是 404，先确认 Composer “看不看得见”这个分支
Composer 默认不会主动扫描 Git 仓库的分支列表，它只信任两种来源：Packagist 上已索引的版本，或你项目
中显式声明的
。直接写
却报错，大概率是因为 Composer 根本没去查那个 Git 仓库。
必须在项目根目录的
里加这段（URL 换成你的真实仓库地址）：
注意：
必须是
，不是
或漏写；
要能直连（私有库需配好 SSH key 或 HTTPS token）；改完后要运行
刷新元数据缓存，不能只靠
。
分支名大小写、前缀、斜杠，一个字符都不能错
Composer 解析
时，会严格匹配远程
下的原始分支名——它不自动转换、不忽略大小写、不补前缀。
要求远程真有叫
的分支，不是
，也不是
对应远程分支名就是
，不是
或
是错的：远程分支若叫
，正确写法是
（前缀
+ 分支名
），但更推荐统一用
写法并配
验证唯一可靠方式是执行：
。没输出 = 分支不存在；有输出如
= 存在且可用。
分支存在但
不显示，可能是缺 branch-alias 或稳定性限制
查不到
，不代表它装不上；但若连
也不列出来，说明 Composer 不认为这是个“可安装版本”。
原因有两个：
Composer 2.9.6
Composer 2.9.6 是 PHP 生态中高效、稳定的依赖管理工具。此版本在性能与兼容性上进一步优化，改进了依赖解析算法，提升大型项目中的安装与更新速度。它支持并行下载任务，显著减少等待时间，并增强了与私有仓库及镜像源的交互稳定性。同时修复了多项命令行交互与内存使用相关的缺陷，确保在复杂依赖关系下依然可靠运行。无论是新项目初始化还是现有系统维护，Composer 2.9.6 都能为开发者提供流畅、精准的依赖管理体验。
下载
远程包的
没设
，Composer 默认不把开发分支当有效版本源
你项目
的
是默认的
，它直接过滤掉所有
前缀版本
临时解法（推荐）：
——
后缀强制允许该包走不稳定通道，不影响其他依赖。
别全局改
到
，否则所有包都可能升到不兼容的 dev 版本，CI 极易崩。
装上了但类找不到，和分支无关，是 autoload 配置没生效
分支拉下来了，
目录里文件也齐全，但 new 一个类就报
？这不是分支问题，是自动加载没注册进去。
立刻做三件事：
运行
，盯住输出里有没有扫到你的目标命名空间（比如
）
打开
，搜索你的命名空间前缀（如
），确认路径指向正确目录
检查类文件路径、
声明、文件名三者是否完全一致：比如
必须对应
，
，且目录名大小写精确匹配
常见坑：PSR-4 配置末尾少反斜杠（
❌ 应为
），或文件被
忽略导致
跳过。
composer.jsonrepositories"vendor/package": "dev-main"composer.json
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/vendor/package.git"
}
]
}
type"vcs""package"urlcomposer update --lockinstalldev-xxxrefs/heads/dev-mainmainmasterMAINdev-feature/loginfeature/loginfeature-logindev/feature/logindev-dev/fixdev/fixdev-dev/fixdev-dev/fixdev/fix"dev/fix"git ls-remote --heads https://github.com/vendor/package.git | grep -i mainabc123 refs/heads/maincomposer showcomposer show vendor/packagedev-maincomposer show -a vendor/packagecomposer.json"extra": {"branch-alias": {"dev-main": "1.0.x-dev"}}composer.jsonminimum-stability"stable"dev-composer require vendor/package:dev-main@dev@devminimum-stabilitydevvendor/package/Class not foundcomposer dump-autoload -vAdding PSR-4 autoload rule for MyLib: src/vendor/composer/autoload_psr4.php'MyLib\'namespaceMyLibHttpClientsrc/Http/Client.phpnamespace MyLibHttp;"MyLib": "src""MyLib\": "src/".gitignoredump-autoload