能跑通 composer require 并让类自动加载的最小闭环只需三件事:composer.json 中 name(小写+短横线+斜杠)、autoload.psr-4(命名空间与路径严格匹配)和 Git tag(v1.2.3 或 1.2.3 格式)缺一不可。
能跑通并让类自动加载的最小闭环,就三件事:正确的、合规的、打对并推上去的 Git tag。
其他全是防翻车或提效用的,不是“必须”,但漏一个就会卡在 Class not found 或 Could not find package。
composer
.json 里哪几个字段不能错
Packagist 抓取时只校验这几个字段,错一个直接拒收,连提交页面都过不去:
必须是小写字母 + 短横线 + 斜杠格式,比如
;
、
、
全非法
显式写成
(Symfony Bundle 才用
)
键必须是完整命名空间加双反斜杠,如
;少一个
或多一个
,Linux 下直接失效
字段不可省,填
最稳妥;缺了 Packagist 页面会标黄警告
删掉
字段——它会被完全忽略,版本靠 Git tag 控制
为什么本地
总是 Class not found
90% 的问题出在 PSR-4 映射和文件实际结构不一致,不是代码写错了:
检查
里的
是否和
的键**逐字匹配**(包括大小写、结尾双反斜杠)
确认类文件名首字母大写,比如
对应
;
在 Linux 下不会被加载
路径值
是相对于
的,不是相对于项目根目录;如果包目录是
,那
就指
改完后别忘了运行
(path 方式下通常自动触发,但手动执行一次更稳)
Git tag 不是“发版仪式”,而是硬性依赖
Composer 版本解析器只认 Git tag,
里的
字段它根本看不见:
Composer 2.9.6
Composer 2.9.6 是 PHP 生态中高效、稳定的依赖管理工具。此版本在性能与兼容性上进一步优化,改进了依赖解析算法,提升大型项目中的安装与更新速度。它支持并行下载任务,显著减少等待时间,并增强了与私有仓库及镜像源的交互稳定性。同时修复了多项命令行交互与内存使用相关的缺陷,确保在复杂依赖关系下依然可靠运行。无论是新项目初始化还是现有系统维护,Composer 2.9.6 都能为开发者提供流畅、精准的依赖管理体验。
下载
合法 tag 格式只有两种:
或
;
、
、
都不算正式版本
打完必须推送到远程:
(
也行,但要确保没漏推)
修改已发布的 tag?别删重打——Packagist 不会刷新,得去后台点 “Update” 或清缓存:
私有包也一样依赖 tag;只是使用方必须额外声明
,否则根本搜不到
本地开发怎么边写边测,不发版也能
别等发版才验证 autoload 是否生效,用
类型仓库模拟真实安装:
在主项目根目录执行:
再运行:
(分支名必须和你本地仓库默认分支一致)
此时
是软链接,改
里代码立刻生效
注意:
方式仅限开发;上线前必须删掉
条目,否则部署环境找不到路径
路径中不能含空格或特殊字符,否则 Composer 会静默跳过该源,不报错也不加载
最常被跳过的其实是命名空间与文件路径的严丝合缝:少一个反斜杠、多一个子目录层级、文件名首字母小写,都会在 Linux 上直接失效——而 Windows 可能恰好不报错,导致上线才发现。
composer requirenameautoload.psr-4namemyorg/http-clientMyOrg/HttpClientmyorg_http_clientmyorg.http-clienttype"library""symfony-bundle"autoload.psr-4"MyOrgHttpClient\": "src/"/license"MIT"versioncomposer requiresrc/HttpClient.phpnamespaceautoload.psr-4HttpClient.phpclass HttpClienthttpclient.php"src/"composer.json./my-http-client"src/"./my-http-client/src/composer dump-autoloadcomposer.jsonversionv1.2.31.2.3dev-mainv1.2release/1.0git tag -a v1.0.0 -m "first release" && git push origin v1.0.0git push --tagscomposer clear-cacherepositoriesrequirepathcomposer config repositories.myclient path ./my-http-clientcomposer require myorg/http-client:dev-mainvendor/myorg/http-clientsrc/pathrepositories