能跑通 composer require 并让类自动加载的最小闭环只需三件事：composer.json 中 name（小写+短横线+斜杠）、autoload.psr-4（命名空间与路径严格匹配）和 Git tag（v1.2.3 或 1.2.3 格式）缺一不可。
能跑通 composer require 并让类自动加载的最小闭环，就三件事：正确的 name、合规的 autoload.psr-4、打对并推上去的 Git tag。 其他全是防翻车或提效用的，不是“必须”，但漏一个就会卡在 Class not found 或 Could not find package。
composer.json 里哪几个字段不能错
Packagist 抓取时只校验这几个字段，错一个直接拒收，连提交页面都过不去：
-
name必须是小写字母 + 短横线 + 斜杠格式，比如myorg/http-client；MyOrg/HttpClient、myorg_http_client、myorg.http-client全非法 -
type显式写成"library"（Symfony Bundle 才用"symfony-bundle"） -
autoload.psr-4键必须是完整命名空间加双反斜杠，如"MyOrgHttpClient\": "src/"；少一个或多一个/，Linux 下直接失效 -
license字段不可省，填"MIT"最稳妥；缺了 Packagist 页面会标黄警告 - 删掉
version字段——它会被完全忽略，版本靠 Git tag 控制
为什么本地 composer require 总是 Class not found
90% 的问题出在 PSR-4 映射和文件实际结构不一致，不是代码写错了：
- 检查
src/HttpClient.php里的namespace是否和autoload.psr-4的键**逐字匹配**（包括大小写、结尾双反斜杠） - 确认类文件名首字母大写，比如
HttpClient.php对应class HttpClient；httpclient.php在 Linux 下不会被加载 - 路径值
"src/"是相对于composer.json的，不是相对于项目根目录；如果包目录是./my-http-client，那"src/"就指./my-http-client/src/ - 改完后别忘了运行
composer dump-autoload（path 方式下通常自动触发，但手动执行一次更稳）
Git tag 不是“发版仪式”，而是硬性依赖
Composer 版本解析器只认 Git tag，composer.json 里的 version 字段它根本看不见：
- 合法 tag 格式只有两种：
v1.2.3或1.2.3；dev-main、v1.2、release/1.0都不算正式版本 - 打完必须推送到远程：
git tag -a v1.0.0 -m "first release" && git push origin v1.0.0（git push --tags也行，但要确保没漏推） - 修改已发布的 tag？别删重打——Packagist 不会刷新，得去后台点 “Update” 或清缓存：
composer clear-cache - 私有包也一样依赖 tag；只是使用方必须额外声明
repositories，否则根本搜不到
本地开发怎么边写边测，不发版也能 require
别等发版才验证 autoload 是否生效，用 path 类型仓库模拟真实安装：
- 在主项目根目录执行：
composer config repositories.myclient path ./my-http-client - 再运行：
composer require myorg/http-client:dev-main（分支名必须和你本地仓库默认分支一致） - 此时
vendor/myorg/http-client是软链接，改src/里代码立刻生效 - 注意：
path方式仅限开发；上线前必须删掉repositories条目，否则部署环境找不到路径 - 路径中不能含空格或特殊字符，否则 Composer 会静默跳过该源，不报错也不加载
最常被跳过的其实是命名空间与文件路径的严丝合缝：少一个反斜杠、多一个子目录层级、文件名首字母小写，都会在 Linux 上直接失效——而 Windows 可能恰好不报错，导致上线才发现。
