Composer包版本发布流程？从Git Tag到Packagist自动更新-composer-PHP中文网

packagist仅识别带v前缀的附注tag（如git tag -a v1.0.0 -m "release"），轻量tag、无v前缀、大写v、非标准后缀或指向无合法composer.json的commit均会导致版本不被索引。

composer包版本发布流程？从git tag到packagist自动更新

Packagist 默认只识别 git tag -a v1.0.0 -m "release" 这类附注 tag，轻量 tag（git tag v1.0.0）大概率被忽略。它不依赖 tag 内容，但会校验 tag 类型和命名格式。

常见失效场景：

安全做法：打 tag 时强制用 -a 和 -m，推送时显式指定 tag 名：git push origin v1.0.0；验证是否成功推送到远端：git ls-remote --tags origin | grep v1.0.0。

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 语法、缺失字段等基础问题。

GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。

下载

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 校验失败。

即使 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，但用户环境因缓存或锁文件卡在旧版本，误以为“发布失败”——其实只是本地没同步元数据。