初始化可发布Composer包需满足：name为vendor/name格式且与Packagist用户名一致；type显式设为library；autoload用psr-4并确保路径真实、命名空间匹配；dev依赖全放require-dev。
怎么初始化一个可发布的 Composer 包
Composer 包本质就是一个带 composer.json 的普通 PHP 项目，但必须满足最低结构要求才能被 Packagist 识别。很多人卡在第一步：本地 git init 后直接 push，结果 Packagist 同步失败，因为缺关键字段。
-
name必须是vendor/name格式（如myname/my-awesome-package），且vendor要和你在 Packagist 注册的用户名一致 -
type建议显式设为library（默认是library，但显式写出来能避免某些工具误判） -
autoload至少要配psr-4，比如"MyName\MyAwesomePackage\": "src/"，路径必须真实存在且命名空间匹配 - 不要加
require一堆 dev-only 工具（如phpunit/phpunit）到根级require，应全放require-dev
示例最小可用 composer.json 片段：
{
"name": "myname/my-awesome-package",
"type": "library",
"autoload": {
"psr-4": {
"MyName\MyAwesomePackage\": "src/"
}
},
"require-dev": {
"phpunit/phpunit": "^10.0"
}
}
为什么 packagist.org 同步不了你的 GitHub 仓库
Packagist 不自动扫描 GitHub，它只响应你手动提交或配置 webhook。常见错误是：点完 “Submit” 就以为完事了，结果等半天没同步，其实根本没触发。
- 提交前确认 GitHub 仓库是 public（私有库无法被 Packagist 索引）
- 在 Packagist 上点击 “Submit” 后，它会跳转到一个表单页，必须填完整 URL 并点 “Check” → “Submit”，不是点完“Submit”就结束
- 更可靠的方式是给 GitHub 仓库配 webhook：Packagist 提供的 endpoint 是
<a href="https://www.php.cn/link/1b97f9e9b29e9fb69eebb6f936b9570b">https://www.php.cn/link/1b97f9e9b29e9fb69eebb6f936b9570b</a>，事件选push和create - 如果已配 webhook 却没反应，检查 GitHub 仓库 Settings → Webhooks 里是否显示 “Last delivery: 2xx”，否则可能是 token 权限不足或 Packagist 账户未验证邮箱
发布时版本号怎么写才不被拒绝
Packagist 对版本有强校验：你不能随便写 "version": "1.0" 这种字段，它只认 Git tag。所有发布动作都基于 tag，不是靠 composer.json 里的 version 字段。
- 正确流程：先 git commit，再
git tag -a v1.0.0 -m "Release v1.0.0"，最后git push --tags - tag 名必须符合 SemVer 规范（
vX.Y.Z或X.Y.Z），v1.0、1.0、dev-master都会被忽略 - 不要用
git tag v1.0.0 -m "..."（少了-a），轻量 tag 没有附带消息，Packagist 可能无法解析 - 发布后别急着改
composer.json里的version—— 它纯属冗余，Packagist 完全不读这个字段
别人 require 你的包却加载不到类
最常发生的不是发布失败，而是发布成功了，别人 composer require myname/my-awesome-package 装上了，但 new MyName\MyAwesomePackage\Foo() 报错 Class not found。
- 检查
src/下文件名是否和类名严格一致（大小写敏感！Linux 服务器上Foo.php里写class foo必然失败） - 确保
composer.json中psr-4的命名空间末尾有反斜杠，比如"MyName\MyAwesomePackage\": "src/"，漏掉结尾\会导致映射失效 - 运行
composer dump-autoload（或装包时加--no-dev后再试）确认 autoloader 是否更新；如果本地开发测试，建议用composer install --no-dev模拟真实使用场景 - 别在
src/里放index.php或其他非类文件——PSR-4 只扫.php文件，但若目录结构和命名空间对不上，整个子树都会被跳过
Packagist 同步快不快不重要，关键是 tag、命名空间、文件路径这三处必须咬死对齐。漏一个斜杠、错一个大小写、少一个 tag，就会让使用者卡在“明明装上了却用不了”的状态，而这种问题往往要花半小时才意识到是 autoload 配错了。
