能跑通 composer require 并让类自动加载的最小闭环只需三件事：composer.json 中 name（小写+短横线+斜杠）、autoload.psr-4（命名空间与路径严格匹配）和 Git tag（v1.2.3 或 1.2.3 格式）缺一不可。
直接上结论：能跑通 composer require 并让类自动加载的最小闭环，就三件事——composer.json 里写对 name、autoload.psr-4 和 Git tag；其他全是锦上添花或防翻车用的。
composer.json 必须填对的三个字段
缺一不可，错一个就进不了 Packagist，或者装了也 Class not found：
-
name：必须是小写字母+短横线+斜杠格式，比如myorg/http-client；不能有大写、下划线、点号；vendor 名最好和你 GitHub/GitLab 用户名一致 -
type：绝大多数情况填"library"；如果是 Symfony Bundle，必须显式写"symfony-bundle"，否则 Flex 不认 -
autoload.psr-4：键是完整命名空间加双反斜杠（如"MyOrgHttpClient"），值是相对于composer.json的真实路径（如"src/"）；结尾那个和/少一个，Windows 下可能不报错但 Linux 下直接失效
本地测试别等发版才动手
开发阶段就该用 path repository 模拟真实安装，避免“发布后才发现 autoload 挂了”：
- 在使用方项目根目录执行：
composer config repositories.myclient path ./my-http-client - 再运行：
composer require myorg/http-client:dev-main（注意分支名要和你本地仓库默认分支一致） - 此时
vendor/myorg/http-client是软链接，改src/里的代码立刻生效，且composer dump-autoload也会自动触发 - 如果类还是找不到，先检查
src/HttpClient.php里的namespace是否和autoload.psr-4键完全一致（包括大小写）
Git tag 不是可选项，是硬门槛
Composer 版本解析只认 Git tag，composer.json 里的 version 字段会被完全忽略：
- 合法 tag 格式只有两种：
v1.2.3或1.2.3；dev-main、feature/x、v1.2都不算正式版本 - 打完必须推送到远程：
git tag -a v1.0.0 -m "first release" && git push origin v1.0.0 - 改过已发布的 tag？别删重打——Packagist 不会自动刷新，得去后台点 “Update”，或清缓存：
composer clear-cache - 私有包也一样依赖 tag；只是使用方项目
composer.json中必须额外声明repositories，否则根本搜不到
最常被跳过的其实是命名空间与文件路径的严丝合缝：src/Client.php 里写 namespace MyOrgHttp;，那 autoload.psr-4 就必须是 "MyOrg\Http\": "src/"，少一个反斜杠、多一个子目录层级、文件名首字母小写，都会让自动加载静默失败。
