Composer找不到依赖包是什么情况_Composer自定义仓库配置教程【方法】-composer-PHP中文网

composer报“package not found”通常因源配置错误（如repositories未置顶、type缺失、url格式不符）、minimum-stability限制、php/扩展不兼容或缓存问题；需用composer show、-vvv日志和curl验证实际生效源。

composer找不到依赖包是什么情况_composer自定义仓库配置教程【方法】

Composer 报“Package not found”几乎从不因为包真的不存在，而是它压根没去你认为该去的地方找——源没配对、顺序错了、认证失效，或者根本没告诉 Composer “这是个仓库”。

为什么 `composer require` 找不到包，但 `composer search` 能搜到

composer search 查的是 Packagist 全局索引，而 composer require 实际安装时受三重限制：当前项目 composer.json 中的 minimum-stability（默认只认 stable）、已锁死的 composer.lock 版本、以及 repositories 的实际生效状态。

如果包只有 dev-main 或 v2.0.x-dev 版本，minimum-stability 是 stable 就会直接跳过，报“not found”而不是“版本不匹配”
运行 composer show vendor/name 看是否已有旧版；若无，再执行 composer require vendor/name --stability=dev --no-update 临时放宽约束
composer search 成功 ≠ 包能装，它不校验 PHP 版本、扩展或依赖兼容性——这些都在安装阶段才触发拦截

`repositories` 配了却没生效的常见硬伤

配了 repositories 却还是走 packagist.org，大概率是以下任意一条没满足：

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

没把自定义源放在 repositories 数组的**首位**：Composer 按顺序匹配，一旦在 packagist.org 找到同名包就终止查找
漏掉显式禁用默认源：{"type": "composer", "url": "https://packagist.org"} 必须和 {"packagist.org": false} 写在同一数组里，且后者不能是独立项
type 写错或缺失：写成 "git"、"github" 或空值，Composer 直接忽略整条；合法值只有 vcs、composer、package、artifact
URL 格式错误：type composer 的 url 必须以 / 结尾（如 "https://pkg.myorg.com/"），否则拼出的 packages.json 请求路径 404

私有 Git 仓库始终 404 的真实原因

不是 URL 不通，而是 Composer 在第一步元数据拉取阶段就失败了——它需要从 Git 仓库中读取 composer.json，并验证其结构合法性。

目标分支（如 main）根目录下必须存在 composer.json，且其中 name 字段格式为 vendor/name（不能是 my-utils 这种单段名）
若按 Tag 安装（如 v1.2.0），该 Tag 对应的 composer.json 中 version 字段必须严格等于 "1.2.0"，否则被跳过
认证不能拼在 URL 里（如 https://token@github.com/...）：必须通过 auth.json 配置，文件权限设为 600，内容结构为 {"http-basic": {"github.com": {"username": "...", "password": "..."}}}
用 curl -I https://github.com/username/repo/raw/main/composer.json 直接测可访问性，比 composer install -vvv 更快定位网络或权限问题

镜像源突然 404 怎么快速验证

阿里云、腾讯云等镜像不是“永久代理”，它们缓存失败响应，一旦上游 packagist.org 临时不可达，后续请求可能持续返回 404，而非穿透重试。

先跑 composer config repo.packagist（项目级）和 composer config -g repo.packagist（全局），确认当前实际生效的源地址
执行 composer clear-cache && composer update -vvv，紧盯日志里 Reading repository 后面的 URL 和 HTTP 状态码
直接测镜像连通性：curl -I https://mirrors.aliyun.com/composer/packages.json，看是否返回 200 和 application/json
Laravel China 镜像（packagist.laravel-china.org）已于 2023 年底停用，还在用必 404

最常被忽略的一点：Composer 不会报“repositories 配置无效”，它只会安静地跳过错误项，然后告诉你“Package not found”。验证是否生效的唯一可靠方式，是看 composer install -vvv 日志里有没有出现你写的 URL 和 Reading repository 字样——没看到，就等于没生效。