答案：Packagist首次抓取仅校验name、type、autoload三字段，name须全小写、无下划线、与账号一致；type必须为library；autoload.psr-4映射末尾须有反斜杠；未打带v前缀的git tag（如v1.0.0）或未推送tag则包不可用；webhook未配置或失效会导致更新不触发。
composer.json 写错 name 字段，Packagist 直接拒收
Packagist 第一次抓取时只校验 name、type、autoload 这三个字段，name 错一个字符就失败。常见错误包括：
-
name含大写字母（MyOrg/http-client❌）、下划线（myorg/http_client❌）或不匹配 Packagist 账号（你在 Packagist 注册的是myorg，但composer.json里写成yourorg/http-client❌） -
type留空或写成project（普通库必须是library） -
autoload.psr-4映射末尾漏了反斜杠，比如"MyOrg\Http": "src/"正确，"MyOrg\Http"（没冒号后内容）或"MyOrg\Http\"（多打了一个反斜杠）都无效
本地验证命令：composer validate。报错就别提交——Packagist 不会告诉你具体哪一行错，只显示 Invalid package information。
Git tag 没推上去，用户根本 require 不到
Packagist 不看分支，只认 git tag。没 tag 就只有 dev-main，用户执行 composer require myorg/my-package 会报 Could not find package，不是网络问题，是压根没稳定版本。
- tag 名必须带
v前缀且符合语义化版本：v1.0.0✅，1.0.0❌，v1.0.0-beta❌（不稳定版默认不被拉取） - 打完 tag 必须显式推送：
git tag v1.0.0之后，要git push origin v1.0.0，不是git push --tags（可能推一堆旧 tag 干扰解析） -
composer.json里别写version字段——它会被忽略，且可能和 tag 冲突；Packagist 完全以 tag 名为准
临时调试可用：composer require myorg/my-package:dev-main，但这不能替代正式发布。
立即学习“PHP免费学习笔记（深入）”；
Packagist 提交后没更新，大概率是 webhook 没配或没生效
你 push 了新 tag，但 Packagist 包页的 Last updated 时间没变，说明它根本没感知到变更。原因通常是：
- GitHub 仓库没配 Packagist webhook：进仓库
Settings → Webhooks → Add webhook，Payload URL 填https://packagist.org/api/github，Content type 选application/json - 提交时用了私有仓库链接（如
git@github.com:...），Packagist 只认 HTTPS 地址（https://github.com/yourname/your-package） - 首次提交失败后，后续修改
composer.json或打新 tag，Packagist 不会自动重试——得去包页点Update手动触发
验证 webhook 是否工作：改完代码、打新 tag、push 后，等 1–5 分钟，刷新 Packagist 包页看 Last updated 时间是否变化。
国内用户配镜像，只加速下载，不解决发布问题
阿里云、腾讯云等 Packagist 镜像只缓存已上线的包，你的新包必须先在官方源 packagist.org 上线，镜像才会同步。配镜像对发布流程毫无影响，但能避免安装慢。
- 全局启用镜像只需一条命令：
composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - 切勿在项目中同时配置多个源（比如既改 global 又在
repositories里写镜像），会导致版本解析混乱，甚至跳过自动更新 - 验证是否生效：
composer config --list | grep repo.packagist，输出应为镜像 URL，不是packagist.org
最关键的细节常被忽略：Packagist 不是上传平台，你每次改完 composer.json，必须打新 tag 并 git push origin v1.0.1，否则用户 require 到的还是旧版——文件改了，但没发版，等于没改。
