Composer如何发布包的预发布版本_Composer包预发布版本发布方案

预发布版本应打形如 v1.0.0-alpha 的 tag，必须带 v 前缀且 identifier 仅限 alpha/beta/rc 及其后缀数字；否则 Packagist 无法识别为有效预发布版本。

预发布版本该打什么 tag？

想让 Packagist 正确识别你的预发布版本，关键在于遵循语义化版本规范中的 pre-release identifier。简单来说，你得使用像 v1.0.0-alpha、v2.3.0-beta.2、v0.9.0-rc.1 这样的格式。这里有两个硬性规定：必须带上 v 前缀，并且标识符只能是 alpha、beta、rc 或者它们后面接数字的形式（比如 alpha.1）。像 dev、preview、test 这类非标准词汇，Packagist 是不认的。

如果你遇到过 composer require vendor/name:1.0.0-alpha 报错 Could not find package，或者列表里只显示 dev-main，那大概率就是踩了这个坑——Packagist 根本没把你的 tag 当作一个有效的版本来索引，要么是格式不对，要么就是标识符不合法。

• v1.0.0-alpha ✅ 合法，会被识别为 1.0.0@alpha
• 1.0.0-alpha ❌ 缺少 v 前缀，很可能被忽略，或者被当作开发分支别名处理
• v1.0.0-dev ❌ dev 不是标准预发布标识符，Packagist 不会将其解析为稳定版或预发布版，而是按开发分支处理
• v1.0.0-preview ❌ 使用了非标准标识符，自然不会出现在 composer show 的版本列表里

用户怎么才能装到 alpha/beta 版？

这里有个常见的误解：以为打了正确的 tag，用户就能直接安装。其实不然。默认情况下，composer require 命令只会拉取 stable（稳定）版本。预发布版本属于 RC 或更低的稳定性等级，用户必须显式指定稳定性标志，或者在项目中放宽限制才行。

具体该怎么操作呢？可以参考下面几点建议：

• 临时安装：直接指定完整的 tag 名，例如 composer require vendor/name:v1.0.0-beta.1。记住，一定要带上 v 前缀。
• 项目级放宽：在项目根目录的 composer.json 中，添加 "minimum-stability": "beta" 配置。同时，建议加上 "prefer-stable": true，这样 Composer 会优先选择稳定版，只在没有稳定版时才 fallback 到预发布版，更安全。
• 避免全局修改：尽量不要通过 config minimum-stability 全局修改稳定性设置，这会影响所有依赖包，容易引发意想不到的冲突。
• CI 测试环境：在持续集成流程中，可以通过环境变量控制，例如设置 COMPOSER_MINIMUM_STABILITY=beta，再配合 composer install --no-interaction --prefer-dist 命令来安装依赖。

预发布版的 autoload 和测试要单独验证吗？

答案是肯定的，而且这一步至关重要。预发布 tag 对应的代码提交，必须包含可正常运行且配置正确的 autoload 信息。否则，即使用户成功 require 了你的包，一旦调用就可能遭遇 Class not found 的错误。要知道，Composer 不会去校验类文件是否存在，它只严格按照 composer.json 里的 autoload 配置来生成类映射。

因此，在打 tag 之前，务必做好以下几项检查：

• 切换到对应的 commit，运行 composer dump-autoload -o 生成优化后的自动加载器，然后手动执行类似 php -r "var_dump(class_exists('Vendor\Class'));" 的命令来验证关键类是否能被找到。
• 确保 psr-4 等命名空间映射路径与实际文件结构完全一致。例如，配置为 "Vendor\": "src/"，那么 src/Class.php 文件中的命名空间就必须声明为 namespace Vendor;。
• 单元测试必须通过。预发布版不等于“勉强能跑”，核心功能路径的测试覆盖必须保证。在 CI 流水线中，至少应该运行 vendor/bin/phpunit --stop-on-failure 这样的命令。
• 切忌依赖 dev-main 分支的配置来“凑合”预发布版。每一个 tag 都是独立的代码快照，配置错了就是错了，没有回旋余地。

Webhook 能自动同步预发布 tag 吗？

能，但前提是配置得当。GitHub 的 Webhook 默认并不会监听 tag 推送事件，你需要手动在设置中勾选 Tag push events，或者选择 Just the push event（并确保推送的是 tag，例如执行 git push origin v1.0.0-beta.1）。

实践中，经常遇到一些配置问题导致同步失效：

• Webhook 地址填错：Payload URL 错误地填成了类似 https://www.php.cn/... 这样的过期或跳转地址。正确的地址应该是 https://packagist.org/api/github。
• Content type 设置不当：如果选成了 application/x-www-form-urlencoded，会导致请求无法被正确处理，必须设置为 application/json。
• 请求未成功：在 Webhook 的 Recent Deliveries 里，如果状态码不是 200，说明请求根本没成功发送到 Packagist。这时，手动点击包页面上的 Update 按钮往往是唯一的补救方法。
• tag 未推送成功：打了 v1.0.0-beta.1 的 tag，但 Packagist 页面的 Last updated 时间戳还是旧的。这时可以先检查 Webhook 日志，再用 git ls-remote --tags origin | grep beta 命令确认 tag 是否真的已经推送到远程仓库了。

最后，有一个容易被忽略的细节：Packagist 不会为预发布版本生成下载统计，也不会自动将其标记为“latest”版本。它的版本列表排序遵循语义化版本规则，但用户最终感知到哪个版本，很大程度上取决于你是否在 README 文档中明确写出了安装命令和该版本的适用场景。