私有包打完 Git tag 后 composer require 找不到，主因是私有包 composer.json 中存在 version 字段，导致 Composer 忽略 Git tag 而只认该硬编码值；必须删除该字段、确保 type 字段合法、使用带 v 前缀的轻量 tag（如 v1.2.0）并推送至远程。
私有包打完 Git tag，composer require 还是找不到？
不是 Composer 没扫描到，而是它压根没去读你的 tag——常见原因是私有包根目录的 composer.json 里写了 "version" 字段。一旦存在，Composer 就忽略 Git tag，只认这个硬编码值；如果值不合法（比如 "1.2.0" 而非 "v1.2.0"），就会直接报 Could not find a matching version of package。
必须做三件事：
- 删掉私有包
composer.json中的"version"字段（整行移除，不要留空字符串） - 确保
"type"字段存在且合法，例如"type": "library" - 用
git tag v1.2.0（带v前缀）+git push origin v1.2.0，缺一不可
为什么 composer update 不拉新 tag？缓存不是清过了吗
composer clear-cache 清的是 ZIP 包和元数据混合缓存，但 Composer 在执行 update 时，默认复用本地缓存的 packages.json（15 分钟内不过期）。哪怕你刚推了 v1.2.0，只要缓存里的索引没刷新，它就看不到这个 tag。
正确做法是强制重载元数据：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 确认当前镜像地址：运行
composer config -g repos.packagist.url，确保指向你的 VCS 镜像或官方源 - 执行
composer update --refresh（仅 Composer ≥ 2.5 支持） - 再跑
composer update vendor/package-name，这时才会识别新 tag - 老版本用户只能手动删缓存子目录：
rm -rf $(composer config --global cache-dir)/repo/https---your-gitlab-domain-com
repositories 配置写错，私有包永远走不了 VCS
私有包仓库必须声明为 "type": "vcs"，否则 Composer 会跳过 Git tag 解析，直接 fallback 到官方源或报错。项目级 composer.json 中的 "repositories" 字段还会完全屏蔽全局镜像配置，导致你以为在用阿里云镜像，实际请求发到了一个已停用的旧地址。
检查和修复步骤：
- 运行
composer config --list | grep repositories.packagist，确认输出是你期望的 URL - 检查项目
composer.json是否含"repositories"，若有，确认其"type"是"vcs"，且"url"指向可访问的 Git 仓库（如https://gitlab.internal.com/vendor/package.git） - 删掉所有非
vcs类型的仓库定义，比如"type": "package"或"type": "path"，它们不支持 tag 自动发现
CI/CD 流水线里 tag 同步失败，根本原因是环境隔离
GitHub Actions、GitLab CI 默认不继承开发者本地的全局 Composer 配置，每次都是干净环境。如果你本地用 composer update 生成了 composer.lock，而 CI 执行 composer install 时却因 repositories 配置缺失或错误，导致它 fallback 到官方源——结果就是锁文件里记录的是 v1.2.0，但 CI 实际装的是 v1.1.0（因为官方源还没同步你的私有 tag）。
关键点在于：
-
composer.lock里记录的是 dist URL 和 commit hash，不是 tag 名；tag 只在update阶段参与解析 - CI 必须显式配置
repositories，不能依赖本地设置 - 建议在 CI 脚本开头加一句：
composer config repositories.myprivaterepo vcs https://gitlab.internal.com/vendor/package.git - 避免在 CI 中用
--no-cache，它会绕过所有缓存，放大网络波动影响；应优先保证元数据准确，而非禁用缓存
