Composer包正式版本标签必须用git tag -a v1.2.3 -m "Release..."创建轻量或附注tag，严格遵循vX.Y.Z语义化格式并推送至远程；dev-main仅为开发快照，非稳定版；私有包需确保Webhook同步、无version字段且repositories设为vcs类型。
如何用 git tag 给 Composer 包打正式版本标签
Composer 本身不负责打标签，它只读取 Git 仓库已有的 git tag。真正打标签的操作必须在包的源码仓库中完成，且 tag 名必须符合语义化版本规范（如 v1.2.3、1.2.3），否则 Composer 无法识别为稳定版本。
常见错误是直接在 composer.json 里改 "version" 字段——这完全无效，Composer 安装时根本不会看这个字段（除非是本地路径仓库且启用了 --no-dev 等特殊模式）。
- 进入包的 Git 仓库根目录，运行：
git tag -a v1.0.0 -m "Release version 1.0.0"
- 推送标签到远程：
git push origin v1.0.0
或一次性推送全部：git push origin --tags
- 确保 tag 指向的是你希望发布的提交（不是空 commit 或 dev 分支头）
- 私有包需确认 Packagist 或私有仓库（如 Satis / Private Packagist）已配置自动抓取或手动同步了新 tag
为什么 dev-main 不被当作稳定版？dev-* 分支别名的含义
dev-main 是 Composer 对 main 分支最新提交的临时版本号映射，它本质是“开发快照”，不是正式发布。即使你把 main 分支保护起来、只允许 PR 合并，只要没打 v* 标签，用户通过 composer require vendor/package 安装的默认仍是 dev-main（如果未设 "minimum-stability"）。
这种行为常被误认为“分支自动发布”，其实只是 Composer 的 fallback 机制：当找不到匹配的稳定 tag 时，就回退到分支的当前 HEAD，并用 dev-branchname 命名。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
dev-main的稳定性等同于dev-develop，受"minimum-stability": "stable"阻止，默认不安装 - 若想让
main分支被当作“稳定开发流”，需显式设置分支别名："extra": { "branch-alias": { "main": "1.0.x-dev" } } - 别名值（如
1.0.x-dev）必须以-dev结尾，且前面部分要能被 Composer 版本约束解析（例如^1.0可匹配1.0.x-dev）
branch-alias 怎么写才生效？常见拼写与作用域陷阱
branch-alias 必须写在包自身的 composer.json 中，且只对当前仓库有效；下游项目无法覆盖或修改它。很多人把它错放在使用方的 composer.json 里，结果毫无作用。
另一个高频问题是键名写错："branch-alias" 是顶层 "extra" 下的子键，不是独立字段，也不是 "autoload" 或 "require" 的兄弟节点。
- 正确结构示例：
"extra": { "branch-alias": { "main": "2.0.x-dev", "develop": "2.1.x-dev" } } - 别名值不能是任意字符串，比如
"latest-dev"无法被^2.0或2.0.*匹配，Composer 会跳过该分支 - 别名仅影响依赖解析阶段，不影响实际安装的代码来源（仍从
main分支拉取） - 一旦打了正式 tag（如
v2.0.0），该别名就不再参与版本选择——tag 优先级永远高于别名
私有包打标签后仍拉不到最新版？检查这几点
私有 Git 仓库（如 GitHub Private、GitLab Self-Hosted）打完 tag，却在项目中 composer update 不到新版本，通常不是 Composer 问题，而是元数据同步或缓存环节断了。
- 运行
composer show vendor/package，确认显示的版本列表是否包含你刚打的v1.2.3；如果没有，说明 Packagist 未感知到更新 - GitHub/GitLab 仓库需开启 Webhook（指向 Packagist 或私有仓库服务），或手动触发同步（如 Packagist 的 “Update” 按钮）
- 本地执行
composer clear-cache，避免旧的 dist 包缓存干扰 - 若用
repositories直接定义 Git 地址，注意"type": "vcs"会强制 Composer 每次都走 Git 协议拉取元数据，但某些网络环境会因 SSH/HTTPS 权限失败而静默回退到旧信息
分支别名和标签都是声明式信号，它们不改变 Git 本身的可访问性。最常被忽略的是：权限、Webhook 是否触发、以及 Packagist 同步日志里有没有报错——这些地方不排查，光改 composer.json 没用。
