Packagist 仅索引公开 Git 仓库中的 composer.json，需满足：仓库公开、含合法 composer.json（含 name、type、autoload）、name 格式为 vendor/package 且 vendor 与 Packagist 账号一致、文件位于 main/master 分支根目录，并在 Packagist 提交 URL；提交失败主因是 name 不匹配、仓库私有、命名不一致或未设 webhook；自动更新依赖语义化 tag（如 v1.0.0）推送，version 字段应留空；autoload 配置错误、缺失 require、PHP 版本约束过严、缺 license 字段亦会导致安装或使用异常。
Packagist 不接受手动上传，必须通过 GitHub/GitLab 等公开仓库自动同步 —— 这是绝大多数人卡住的第一步。
你的 GitHub 仓库是否满足 Packagist 的自动发现前提？
Packagist 本身不托管代码，只索引公开 Git 仓库中的 composer.json。要被成功抓取，必须同时满足：
- 仓库为 公开（public），且包含合法的
composer.json（至少有name、type、autoload） -
name字段格式为vendor/package，且vendor必须与你的 Packagist 账号用户名完全一致（大小写敏感） - GitHub 仓库的
main（或master）分支根目录下存在该文件 - 你已在 Packagist 登录并点击右上角 “Submit” 输入仓库 URL（如
https://github.com/yourname/your-package）
为什么提交后显示 “Package not found” 或 “Invalid package name”？
这是最常触发的失败提示，原因集中在命名与权限上：
-
composer.json中的name值（如"myorg/my-pkg"）和你在 Packagist 注册的用户名（myorg）不一致 → 修改name或改用对应账号提交 - GitHub 仓库设为私有 → Packagist 无法读取，必须设为 public
- 仓库名含下划线（
my_pkg）但name写成短横线（my-pkg）→ Packagist 严格校验，二者必须完全一致 - 未在 GitHub 设置 Packagist webhook（虽非必需，但推荐启用：进入仓库 Settings → Webhooks → Add webhook，Payload URL 填
https://packagist.org/api/github）
如何让 Packagist 自动更新新版本（tag）？
Packagist 默认只扫描 main 分支的最新 commit，但真正发布稳定版靠的是 Git tag。你需要：
立即学习“PHP免费学习笔记（深入）”；
- 本地打符合语义化版本规范的 tag：
git tag -a v1.0.0 -m "Release v1.0.0" - 推送到 GitHub：
git push origin v1.0.0（注意不是git push --tags，后者可能推送过多历史 tag） - 确保
composer.json中的version字段 不要填写 —— Packagist 会从 tag 名自动提取版本号；填了反而可能导致冲突或忽略 tag - 等待 Packagist 自动轮询（通常 1–5 分钟），或手动进入包页面点击 “Update” 按钮强制刷新
常见但容易被忽略的细节
很多包能上线却无法被正常 require，问题往往藏在配置深处：
-
autoload没配对：用"psr-4"就必须保证命名空间前缀与目录结构匹配，否则composer install后类找不到 - 缺少
require声明：即使依赖的是 PHP 核心扩展（如ext-json），也应显式写进composer.json的require或require-dev，否则用户安装时无提示 - PHP 版本约束太激进：
"php": "^8.2"会直接拦住所有 8.1 用户，而实际代码可能完全兼容 → 用"php": ">=7.4"更稳妥 - 未设置
license字段：Packagist 不强制，但没有许可证的包会被 Composer 警告，且多数公司政策禁止引入无明确 license 的依赖
