Packagist仅识别带v前缀的附注tag（如git tag -a v1.0.0 -m "release"），轻量tag、无v前缀、大写V、非标准后缀或指向无合法composer.json的commit均会导致版本不被索引。
Git tag 必须是 annotated tag，且带 v 前缀
Packagist 默认只识别 git tag -a v1.0.0 -m "release" 这类附注 tag，轻量 tag（git tag v1.0.0）大概率被忽略。它不依赖 tag 内容，但会校验 tag 类型和命名格式。
常见失效场景：
- 用
git tag v1.0.0打出轻量 tag，再git push --tags—— Packagist 不触发更新 - tag 名写成
V1.0.0、1.0.0或release-v1.0.0—— 不符合默认匹配规则，版本不显示 - tag 指向的 commit 根目录没有
composer.json，或该文件语法错误 —— 抓取失败且无提示
安全做法：打 tag 时强制用 -a 和 -m，推送时显式指定 tag 名：git push origin v1.0.0；验证是否成功推送到远端：git ls-remote --tags origin | grep v1.0.0。
composer.json 的 name 和 autoload 字段不能错一个字符
Packagist 首次抓取时对 composer.json 的校验极严，错一个字段就直接报 Invalid package information，不会给出具体哪行出错。
关键约束：
-
name必须是全小写vendor/package-name格式，且vendor必须与你在 Packagist 注册的用户名完全一致（不是 GitHub 用户名，除非已手动绑定） -
autoload至少含psr-4，命名空间末尾必须有双反斜杠，路径末尾必须有斜杠/，例如：{"psr-4": {"MyOrg\Http\": "src/"}} - 删掉
version字段 —— 它被完全忽略，留着反而可能干扰 CI 或导致校验警告 -
type显式设为"library"，否则某些旧版 Packagist 可能拒绝索引
本地验证命令：composer validate --strict，它不能替代 Packagist 校验，但能提前暴露 JSON 语法、缺失字段等基础问题。
部署一个包含 4 个智能体（agent）的数字孪生平台。在以下情况下使用该技能： 1. 用户希望为物理资产监控与预测性维护等场景搭建数字孪生系统……
GitHub Webhook 是自动更新的唯一可靠方式
2023 年底起 Packagist 彻底关闭自动发现机制。没配 webhook，每次发新 tag 都得手动点包页右上角的 Update 按钮 —— 实际项目中极易遗漏，造成“已发版但用户装不到”的现象。
正确配置要点：
- Payload URL 填
https://packagist.org/api/github（不是带?username=的旧地址，也不是镜像站） - Content type 选
application/json - Events 勾选
Just the push event（覆盖 tag 推送）或Releases（如果你用 GitHub Releases） - 保存后立即测试：
git tag v1.0.1 && git push origin v1.0.1，几秒内 Packagist 页面应刷新Last updated时间
若测试失败，去 GitHub 仓库的 Settings → Webhooks → Recent Deliveries 查状态码：200 表示成功，404 通常意味着 URL 错误，422 多因 composer.json 校验失败。
用户 require 不到新版本？先查缓存、锁文件和语义化约束
即使 Packagist 页面已显示新 tag，composer require vendor/name:^1.0 仍可能拉不到，原因往往不在发布侧。
高频排查点：
- 本地执行
composer clear-cache—— Composer 缓存元数据，旧缓存会导致看不到新版本 - 运行
composer show vendor/name确认 Packagist 返回的可用版本列表里是否真有v1.0.1 - 检查项目根目录是否存在
composer.lock，若存在且锁定了旧版本，需composer update vendor/name（不要加--lock） - 注意语义化版本规则：
^1.0不匹配v2.0.0，dev-main默认不被拉取（minimum-stability是stable时）
最易被忽略的是：Packagist 页面显示了新 tag，但用户环境因缓存或锁文件卡在旧版本，误以为“发布失败”——其实只是本地没同步元数据。
