composer扩展包版本号必须严格遵循semver格式（major.minor.patch），仅靠git tag名称生效且须推送至远端；packagist据此同步版本，手动写composer.json的version字段无效。
Composer扩展包的版本号必须遵循语义化版本（SemVer）
Composer 默认只认 MAJOR.MINOR.PATCH 格式，比如 2.3.1 或 3.0.0。任何非标准写法（如 v1.2.3、1.2.3-beta、1.2）都会导致依赖解析失败或警告。
你不能靠 Git tag 名称“假装”是版本——Composer 只看 composer.json 里的 "version" 字段（不推荐硬写），或更关键的是：Git tag 的名称本身必须严格匹配 SemVer 格式，并且要推送到远端仓库。
- 正确 tag：
v2.1.0、1.0.0（前面带v是惯例，但不是强制；关键是数字结构） - 错误 tag：
release-2.1、beta2、2.1（缺 PATCH）、v2.1.0-final（含非法字符）
发布稳定版前必须打 Git tag 并推送
Composer 不从 composer.json 读取版本号来分发包，而是通过 Packagist（或私有仓库）抓取你的 Git 仓库 tag。如果你没打 tag，Packagist 就只能看到 dev-main 这类开发分支别名，下游用户无法用 "yourvendor/yourpkg": "^2.1" 安装稳定版。
标准操作流：
- 更新代码并测试通过
- 修改
composer.json中的"description"或其他元信息（可选） - 执行：
git tag v2.1.0 - 执行：
git push origin v2.1.0（注意：不是git push --tags，避免误推大量旧 tag） - 等待 Packagist 自动更新（或手动触发 hook）
预发布版本要用 -alpha/-beta/-rc 后缀，且设 "minimum-stability"
想让用户能安装测试版，不能只打 v2.2.0-alpha1 就完事。Composer 默认只允许安装 stable 版本，所以必须显式声明稳定性策略：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 在包自己的
composer.json中设置："minimum-stability": "alpha"（或beta/rc） - 同时加
"prefer-stable": true防止意外拉到不稳定依赖 - 下游项目若要 require 该预发布版，需在自己的
composer.json中也设"minimum-stability": "alpha"，或用完整约束："yourvendor/yourpkg": "2.2.0@alpha"
注意：@alpha 这种写法仅用于临时指定，长期维护应靠 minimum-stability + tag 后缀协同控制。
不要手动改 composer.json 里的 "version"
这个字段在扩展包中几乎没用——Packagist 忽略它，Composer 安装时也不读它。很多开发者误以为写了 "version": "2.1.0" 就等于发布了 2.1.0，结果发现 Packagist 显示的还是 dev-main。
真正起作用的只有两件事：
- Git 仓库打了符合 SemVer 的 tag（如
v2.1.0）并推送 - Packagist 已绑定该仓库且 webhook 正常触发
删掉 "version" 字段反而更干净，避免误导自己或协作者。
composer update 始终拉不到——这时要手动登录 Packagist 点击 “Update” 按钮，或重置 hook。
