Composer 默认只同步 stable 版本，dev 分支和预发布版（如 v11.0.0-beta1）不会被镜像收录；需用 --stability-dev 或配置 repositories 显式启用非 stable 源。
镜像源里找不到刚发布的框架包，不是镜像“没同步全”，而是 Composer 默认过滤了 dev 分支、预发布版本（alpha/beta/rc）和未标记 stable 的包；国内镜像本身也按此规则同步，你看到的“缺失”其实是预期行为。
为什么 laravel/framework 的 dev-main 或 v11.0.0-beta1 在镜像里查不到
Composer 的元数据索引（packages.json 和 p/vendor/package.json）默认只收录 stable 版本。即使 Packagist 页面显示了 dev-main，镜像站也不会拉取它——因为同步脚本加了 --stability=stable 参数。
-
composer show laravel/framework查不到dev-main，但composer show -a laravel/framework可能列出部分非 stable 版本（取决于本地缓存是否含 provider 元数据） - 想强制安装开发分支，必须显式指定稳定性：
composer require laravel/framework:dev-main --stability-dev - 镜像站（如阿里云、腾讯云）不会同步
dev-前缀分支或-alpha/-rc后缀版本，这不是 bug，是设计使然 - 若你依赖的是私有 fork 的
dev-feature/x，必须在repositories中声明"type": "vcs"，且 URL 指向 Git 仓库，不能指望镜像代劳
composer update --refresh 仍找不到新框架包？先确认是否真被镜像收录
执行 --refresh 只能刷新你本地缓存的元数据，但如果镜像源压根没同步那个包，刷新也没用。关键要验证镜像端是否存在。
- 直接请求镜像的 p2 接口：
curl -s https://mirrors.aliyun.com/composer/p/laravel/framework.json | jq -r '.packages."laravel/framework" | keys[]' | sort | tail -3 - 对比官方源：
curl -s https://packagist.org/p2/laravel/framework.json | jq -r '.packages."laravel/framework" | keys[]' | sort | tail -3 - 如果镜像输出里没有你要的版本（比如缺
v11.0.0），说明同步延迟或被过滤；此时等不如换源，中科大镜像有时比阿里云快 10–20 分钟 -
composer update --refresh -v日志中若出现Reading packages.json from cache at /https---mirrors-aliyun-com-composer/，说明走对了镜像；若出现Downloading https://packagist.org/，说明项目级repositories覆盖了全局配置
项目级 repositories 配置导致框架包“消失”的典型场景
只要 composer.json 里有 "repositories" 字段，Packagist 官方源和所有镜像都会被绕过——除非你显式把它加回去。很多框架模板（如 Laravel Breeze）自带空数组，这是隐形陷阱。
立即学习“PHP免费学习笔记（深入）”；
- 运行
composer config repositories，如果输出非空，哪怕只是[]，就已禁用镜像 - 常见错误写法：
"repositories": [{"type": "vcs", "url": "git@github.com:myorg/mylib.git"}]—— 这会完全屏蔽packagist.org，连monolog/monolog都可能装不上 - 正确写法（保留 packagist 并启用镜像）：
"repositories": [{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}, {"type": "vcs", "url": "git@github.com:myorg/mylib.git"}, {"packagist.org": false}] - 临时诊断：删掉
repositories字段再跑composer show laravel/framework，若立刻能查到，问题就定位清楚了
最易被忽略的一点：框架包的 composer.json 里若声明了 "minimum-stability": "dev"，它会影响整个项目的解析逻辑，导致其他包的版本约束被放宽或收紧——这种跨包稳定性传染，比镜像同步问题更难排查。
