新发布的 Composer 包在 require 时提示“Package not found”是因为 Packagist 索引未同步，需手动提交包并启用 webhook 才能自动更新；首次发布后常因未收录或缓存延迟导致搜索失败。
新发布的 Composer 包在 composer require 时提示 Package not found，不是你输错了，也不是包不存在——是 Packagist 的索引还没同步。
为什么刚 `git tag` 发布就搜不到？
Packagist 不是实时监听 GitHub/GitLab 的每个 push 或 tag。它依赖「主动通知」或「轮询抓取」，而新仓库默认没有开启自动更新，首次提交后尤其容易卡在“未收录”状态。
- GitHub 仓库需手动触发一次 Packagist 同步（或配置 webhook）
- 私有包、非 GitHub 源、或未公开的仓库，Packagist 根本不会扫描
- 即使已收录，搜索缓存可能延迟 5–30 分钟，
composer search会返回空
怎么确认包是否已被 Packagist 收录？
别只信本地 composer require 报错，直接查源头：
Pilot Digital Twin Setup
下载
部署一个包含 4 个智能体（agent）的数字孪生平台。在以下情况下使用该技能： 1. 用户希望为物理资产监控与预测性维护等场景搭建数字孪生系统……
- 打开
https://packagist.org/packages/{vendor}/{package}（比如https://packagist.org/packages/myorg/my-new-lib） - 如果显示 404，说明 Packagist 还没收录；如果显示页面但版本为空，说明 repo 已关联但无有效 tag
- 检查 GitHub 仓库主页右上角是否有 Packagist 小图标 —— 没有就代表没绑定
如何强制让 Packagist 立刻收录新包？
最稳的方式是手动提交到 Packagist，并确保后续自动更新：
- 登录
packagist.org，点击右上角「Submit」→ 填入 GitHub/GitLab 仓库 URL - 提交后，进入该包的 Packagist 页面 → 「Edit」→ 开启
Update on Push（即配置 webhook） - 若已提交过但没生效，点页面上的
Force update按钮（仅对已关联包可见） - 确保你的 Git tag 符合规范：用
v1.0.0或1.0.0，不能是release-1.0或带空格/下划线
临时绕过 Packagist 直接装本地新包？
开发调试阶段，不依赖 Packagist 也能验证安装逻辑：
- 在项目根目录
composer.json中加repositories段，指向本地路径或 Git URL：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/your-new-package"
}
]
- 然后运行
composer require yourname/your-new-package:dev-main（或具体 tag，如v0.1.0） - 注意：
dev-main需要 GitHub 默认分支确实是main；否则换成dev-master或对应分支名
真正卡住的往往不是语法或命令，而是以为“发布即可见”，结果在 Packagist 页面刷新了八遍才发现根本没进它的库。手动提交 + 开启 webhook 是一劳永逸的起点，别跳过这步。
