包名拼错或大小写不一致是“Package not found”主因，需严格匹配Packagist URL路径；私有包须配置合法repositories；国内镜像可能不同步，应切回官方源并清缓存验证。
包名拼错或大小写不一致直接导致“not found”
Composer 对包名是严格大小写敏感的，monolog/monolog 和 monolog/Monolog 是两个完全不同的包。它不会自动纠正、也不会提示“您是不是想搜这个”。常见错误包括：
- 把
spatie/laravel-backup写成spatie/backup - 漏字母：比如
guzzlehttp/guzzle写成guzzle/guzzle - 用连字符代替斜杠：
laravel-sanctum而不是laravel/sanctum
最稳的验证方式是打开浏览器，访问 https://packagist.org/packages/<vendor>/<name></name></vendor>（例如 https://packagist.org/packages/laravel/sanctum），看是否 200 可访问。别信搜索结果里的模糊匹配。
私有包没配 repositories，Composer 根本不去找
Composer 默认只查 Packagist 官方源，对 GitHub、GitLab 或内网 Git 仓库完全无视——除非你明确告诉它“去那儿翻”。composer.json 里 repositories 配置错一个字段（比如漏掉 "type": "vcs"），它就会静默跳过，继续回默认源报错。
正确写法示例：
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/mygroup/mylib.git"
}
]
注意点：
- URL 必须是可直接
git clone的地址，不能是网页版地址 - 如果仓库需要认证（如 GitHub private repo），确保已配置
auth.json且 token 有read:packages权限 - 分支或 tag 名（如
"dev-main"）必须真实存在，不能是本地未 push 的分支
镜像源不同步或已停用，换源前先确认
国内镜像（阿里云、腾讯云）只是缓存，不是“魔法源”。新发布的包、dev 分支、刚打的 tag，很可能还没同步；更糟的是，有些旧镜像（如 packagist.laravel-china.org）早在 2023 年底就停用了，但配置还留在 composer config -g 里，一用就 404。
快速诊断步骤：
- 运行
composer config -g repo.packagist看当前全局源 - 若输出是
{"url":"https://packagist.phpcomposer.com"}这类已失效地址，立刻换掉 - 临时切回官方源验证：
composer config -g repo.packagist https://packagist.org - 换源后务必执行
composer clear-cache，否则缓存仍指向旧地址
别迷信“换镜像就能解决”，尤其对私有包——公共镜像压根不会同步你的内网仓库。
PHP 或 Composer 版本不满足包要求，会“假装找不到”
某些包在 composer.json 的 require 字段里写了硬性约束，比如 "php": ">=8.0" 或 "composer-plugin-api": "^2.0"。如果你本地是 PHP 7.4 或 Composer 1.x，Composer 解析器会直接过滤掉所有可用版本，最终报 Package not found ——它不是网络问题，也不是拼写问题，而是“条件不达标，不给你看”。
排查方法：
- 运行
php -v和composer --version - 打开该包的 Packagist 页面 → 点
Requires标签页，核对约束 - 临时绕过（仅调试）：
composer require vendor/name --ignore-platform-reqs - 长期方案：升级 PHP/Composer，或改用兼容旧版的版本号（如
"spatie/laravel-ray": "1.29.*"）
最容易被忽略的是：CLI 和 Web 环境的 php.ini 可能不同，php -m 查到的扩展列表，未必是你跑 php artisan 时实际加载的。
