答案是composer默认不安装开发分支（如dev-main），需显式允许不稳定版本：检查minimum-stability设置、确认远程分支真实存在、配对vcs仓库及认证，并避免误用已废弃的dev-master别名。
报错“Could not find a matching version of package”且提示 dev-main 或主干分支不存在
这不是网络问题，也不是权限问题，而是 Composer 默认不拉取开发分支（如 dev-main、dev-master），除非你明确告诉它“允许不稳定版本”。
常见现象是执行 composer require vendor/package:dev-main 或在 composer.json 里写 "vendor/package": "dev-main" 后报错，但包确实存在——只是它没打任何 stable 标签，只有 git 分支。
- 检查包真实状态：打开
https://packagist.org/packages/vendor/package，确认是否有dev-main标签显示；没有？那说明作者根本没 push 到 Packagist，或仓库未同步 - 确认 minimum-stability 设置：如果项目
composer.json中有"minimum-stability": "stable"（默认值），就必须显式覆盖该包的稳定性，例如："vendor/package": "dev-main as 1.0.0"或加--stability=dev参数 - 别依赖
dev-master：这个别名已废弃多年，现代 Composer（2.2+）默认不识别；一律改用dev-main，并确保远程仓库主分支名确实是main - 私有 Git 仓库要配 repositories：如果包不在 Packagist 上，必须在
composer.json的repositories里声明 type: "vcs"，且 URL 可访问（HTTPS 需 token，SSH 需密钥）
运行 composer install 却提示找不到 dev-main，但 composer update 能装
这是 lock 文件的“记忆效应”在作祟。composer install 只按 composer.lock 里的精确版本还原，而 composer.lock 里记录的是当时解析出的 commit hash；如果那个 commit 已被 force-push 覆盖或分支被重置，install 就会失败。
此时不是源的问题，也不是包删了，而是 lock 记录失效了。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 先验证：运行
composer show vendor/package，看是否能查到包信息；能查到 → 说明源和包都正常，只是 lock 过期 - 不要直接删
composer.lock：它可能包含其他关键约束；优先尝试composer update vendor/package --with-dependencies单独刷新该包及其依赖 - 若必须重建 lock：删掉
composer.lock后运行composer update --lock（不是install），它会重新求解并生成新 lock，但注意这会更新所有包，不只是目标包 - Git 分支变动频繁的团队，建议在
composer.json中用"reference"锁 commit，而非依赖分支名：例如"dev-main#abc1234"
报错含 “Reference … could not be resolved” 或 “Branch does not exist”
说明 Composer 找不到指定分支或 commit，但错误常被误读为“包不存在”。实际原因集中在 Git 层面。
典型场景：你在 repositories 里配置了 GitHub 仓库，但该仓库是私有的，或未启用 GitHub Packages，或分支名拼错（比如写成 dev-master 但实际是 dev-main）。
- 手动测试 Git 可达性：运行
git ls-remote https://github.com/vendor/repo.git，看能否列出分支；返回空或 403 → 权限/URL 问题 - HTTPS 私仓必须带 token：URL 应为
https://<token>@github.com/vendor/repo.git</token>，否则 Composer 无法认证 - SSH 私仓要确保
~/.ssh/id_rsa存在且 agent 已加载：运行ssh -T git@github.com验证通路 - 别信 IDE 或网页显示的分支名：GitHub 界面顶部显示的“main”可能是默认分支，但仓库实际可能设为
develop；用git ls-remote查真实分支列表最准
为什么换镜像源也解决不了 “找不到主干版本”？
因为镜像源（如阿里云）只同步 Packagist 上已收录的包和版本，**不代理 VCS 仓库（GitHub/GitLab）的原始 Git 请求**。如果你用的是 type: "vcs" 源，Composer 会绕过镜像，直连 GitHub —— 此时 DNS、防火墙、Token 权限才是瓶颈，换源无效。
- 判断是否走镜像：运行
composer config -g repo.packagist，如果输出是https://mirrors.aliyun.com/composer/，说明 Packagist 包走镜像；但 vcs 包永远直连 - 排查直连失败：用
curl -I https://api.github.com/repos/vendor/repo测试 API 是否可达；返回 403 或超时，就不是 Composer 的问题 - 企业内网常见坑：Git over HTTPS 被中间人证书拦截，临时解决可加
composer config -g github-protocols https，但更稳妥的是把 CA 证书加入 PHP 的openssl.cafile - 别在
repositories里混用 type：一个仓库只能有一种 type；"type": "package"和"type": "vcs"不能共存于同一配置块
