私有仓库打 tag 后 composer require 找不到包，根本原因是 packagist 未识别：tag 必须是轻量 tag（如 git tag v1.2.3）、版本号需合法且带 v 前缀、必须推送至远程、对应 commit 需含匹配 name 和 version 的 composer.json、仓库需启用自动同步、require 版本写法要正确、repositories 中须禁用默认 packagist 源。
私有仓库打 Tag 后 composer require 仍找不到包？不是没推，而是 Packagist 没认出来——关键在 Tag 格式、composer.json 内容、远程同步三者必须严丝合缝。
Tag 必须是轻量 Tag，且带合法语义化版本号
Composer（尤其旧版 Packagist）只识别轻量 Tag：git tag v1.2.3 ✅，不认带注释的 git tag -a v1.2.3 ❌。如果用了 -a 但没写 message，Packagist 可能解析失败；写了 message 也不保险，因为 Packagist 不解析 Annotated Tag 的元数据。
版本号必须符合 SemVer 规范，且不能含非法字符：
-
v1.2.3✅ -
v1.2.3-beta.1✅ -
v1.2.3+build.1❌（+后缀会被 Packagist 跳过） -
1.2.3❌（缺v前缀，Packagist 不识别）
打完务必推送到远程：git push origin v1.2.3。只本地 git tag 没用，Packagist 完全看不到。
Tag 对应的 commit 必须含有效 composer.json
这个 commit 的根目录下，composer.json 文件必须存在，且其中 "name" 字段值要和你在业务项目中 require 的包名完全一致（包括大小写和斜杠方向），例如：
{"name": "acme/internal-sdk", ...}
同时，"version" 字段值必须与 Tag 名严格匹配：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Tag 是
v1.2.3→"version": "1.2.3"或"version": "v1.2.3"都可（新版 Composer 接受两者） - Tag 是
v1.2.3-beta.1→"version": "1.2.3-beta.1"必须一致，不能写成"1.2.3-beta1"
如果 composer.json 缺失或 name/version 不匹配，Packagist 同步时会静默跳过该 Tag，composer show acme/internal-sdk 就查不到这个版本。
仓库需启用自动更新，且 Packagist 能访问到 Git 源
如果你把私有仓库提交到了 packagist.org（或私有 Packagist 实例），必须手动开启 Webhook 自动同步：
- 进入该包在 Packagist 的 Settings 页面
- 勾选
Automatically update the package on new commits? - 确保你的 Git 仓库（如 GitLab）已配置对应 Webhook，指向 Packagist 的回调地址
如果用的是自建 Satis 或 Artifactory，要注意：
- Satis 构建后，
packages.json必须能被curl -I https://satis.example.com/packages.json直接返回 200 - Artifactory 的 Composer 仓库 URL 末尾必须带
/，比如https://artifactory.example.com/artifactory/api/composer/my-repo/
否则 Composer 会 fallback 到 packagist.org，报 Could not find package，而你根本不知道它压根没连你的私有源。
require 版本写法必须匹配 Git 引用类型
Composer 对 vcs 类型仓库不做静态版本索引，而是实时解析 Git 分支/Tag。所以 require 的值不是“随便写个版本号就行”：
- 想装 Tag：写
"acme/internal-sdk": "^1.2.3"或"acme/internal-sdk": "1.2.3"——Composer 会去找v1.2.3这个 Tag - 想装分支最新：写
"acme/internal-sdk": "dev-main"——要求远程仓库存在main分支，且该分支根目录composer.json的name匹配 - 混用没问题：
dev-main和v1.2.3完全可以共存，开发用dev-main，发布走 Tag
最容易忽略的一点：如果你在 repositories 里加了私有源，但没显式禁用默认源，Composer 会优先查 packagist.org，哪怕你的私有包已正确打标、同步成功，它也不会去私有源找——必须加兜底项：{"type": "composer", "url": "https://packagist.org", "packagist": false}，否则整个流程就卡在第一步。
