composer 不负责打 git tag，仅读取 composer.json 中的 version 字段；git tag 需由 ci 脚本解析该字段后显式执行 git tag 和 git push --tags，且须校验 tag 是否已存在、使用 v 前缀、配置 packagist webhook 并确保 github_token 有写权限。
Composer 本身不负责打 Git Tag，它只读取 composer.json 中的版本号
很多人以为 composer install 或 composer update 会自动创建或更新 Git Tag —— 不会。Composer 的版本字段（如 "version": "1.2.3"）只是静态声明，Git Tag 是独立操作，必须由外部工具（比如 CI 脚本）显式执行 git tag 和 git push --tags。
真正起作用的是：CI 在检测到主干合并（如 main 或 master）后，解析 composer.json 的 version 字段，再调用 Git 命令打标。这个过程和 Composer 没有运行时耦合，只是约定读取位置。
- 如果
composer.json里写的是"version": "dev-main"，CI 就没法提取有效语义化版本 —— 必须是x.y.z格式（或带-alpha等后缀） - 本地改了
version但没git add+git commit，CI 拿到的就是旧版本号 - CI 脚本里别直接用
jq '.version' composer.json，Windows 或 BusyBox 环境可能没jq；推荐用 PHP 一行命令：php -r "echo json_decode(file_get_contents('composer.json'), true)['version'] ?? '';"
GitHub Actions 中实现「合并到 main 后自动打 Tag」的关键步骤
核心逻辑是：监听 push 到 main 分支 → 提取 composer.json 版本 → 检查该 Tag 是否已存在 → 打标并推送。
容易漏掉的点是「避免重复打标」：同一版本号如果被多次合并，第二次就会因 Tag 已存在而失败。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 务必加条件判断：
git ls-remote --tags origin | grep -q "v${VERSION}$"，否则 CI 可能报错fatal: tag 'v1.2.3' already exists - Tag 名称建议统一加
v前缀（如v1.2.3），和 Packagist 兼容性更好；不加前缀时需在composer.json的repositories里显式配"no-api": true，否则 Packagist 可能无法识别 - 使用
actions/checkout@v4时，默认不带 Git Tag 历史，得加参数：fetch-depth: 0，否则git ls-remote查不到远端已有 Tag
打完 Tag 后，Packagist 为什么没立刻同步？
Packagist 不轮询 Git，它依赖 Webhook 或手动触发。即使你成功推了 v1.2.3，Packagist 也不会自动感知，除非满足以下任一条件：
- 你在 Packagist 页面点击 “Update”（手动）
- 你在 Packagist 项目设置里配置了 GitHub/GitLab Webhook，并且推送的 Tag 匹配其正则（默认是
^v?[\d.]+$） - 你用
packagist.org提供的 API 触发更新（需要apiToken）
常见错误：Webhook 配置了，但 Tag 名是 1.2.3（没 v），而 Packagist 默认正则不匹配，结果“推了等于没推”。验证方法是看 Packagist 项目页的 “Recent Activity”，如果没有新记录，大概率是 Webhook 没生效或正则不匹配。
CI 打 Tag 失败的三个高频错误信息及修复
这些不是 Composer 错误，而是 Git + CI 权限/环境导致的典型卡点，看到就该直接查对应环节：
-
error: src refspec refs/tags/v1.2.3 does not match any→ 本地没git tag v1.2.3，只有git tag -a或git tag -m才算真正创建；光改composer.json不算 -
remote: Permission to user/repo.git denied to github-actions[bot]→ GitHub Actions 默认 token（GITHUB_TOKEN）没有 push tag 权限，需在 workflow 里显式加permissions: contents: write -
fatal: could not read Username for 'https://github.com': No such device or address→ 用 HTTPS 方式 push 时没配凭据；应改用 Git SSH（git@github.com:user/repo.git）或用GH_TOKEN注入凭据（https://${{ secrets.GH_TOKEN }}@github.com/user/repo.git）
所有这些环节里，最常被跳过的其实是「本地先手动跑一遍 CI 脚本里的关键命令」—— 比如复制出打 Tag 那几行，在自己机器上用真实值试一次，比对着文档猜强得多。
