Packagist仅索引公开Git仓库的composer.json，要求name格式为vendor/name且与Packagist用户名一致、含autoload（推荐PSR-4）、无version字段，需打v1.0.0等语义化标签才能安装稳定版本。

你的代码仓库必须是公开的 Git 仓库

Packagist 不托管代码，只索引和分发。它只支持从公开的 GitHub、GitLab、Bitbucket 等 Git 仓库自动抓取 composer.json 文件。私有仓库无法被 Packagist 直接识别，除非你自建 Satis 或使用 Private Packagist 服务。

确保：

• 仓库在 GitHub 上已设为 Public
• composer.json 文件位于仓库根目录
• 该文件中至少包含 "name"（格式为 vendor/name，如 myname/my-php-library）、"autoload" 和 "type": "library"

composer.json 必须满足 Packagist 的基本校验规则

Packagist 在添加包时会校验 composer.json 的合法性。常见失败原因不是语法错误，而是语义缺失或冲突：

• "name" 必须符合 vendor/package 格式，且 vendor 名需与你在 Packagist 注册的用户名一致（例如你在 Packagist 的用户名是 myname，就不能用 acme/mylib）
• "autoload" 必须存在，推荐用 PSR-4：

  {
      "autoload": {
          "psr-4": {
              "MyName\\MyLibrary\\": "src/"
          }
      }
  }

• 不要写 "version" 字段 —— Composer 依赖 Git tag 自动识别版本，手动写反而会导致冲突
• 如果用了 PHP 扩展依赖（如 ext-curl），请确认它们在 "require" 中声明为 "ext-curl": "*"，而非 "curl": "*"

在 Packagist 上提交仓库后，必须打 Git tag 才能安装指定版本

提交仓库 URL 到 Packagist 后，它会立即抓取 composer.json 并建立包条目，但此时只能通过 dev-main（或 dev-master）安装开发分支。要安装稳定版本，必须打符合语义化版本规范的 Git tag：

• 运行 git tag -a v1.0.0 -m "Release v1.0.0"
• 推送标签：git push origin v1.0.0（注意不是 git push --tags，后者可能推送过多旧 tag）
• Packagist 默认每 15 分钟轮询一次更新；也可在 Packagist 包页点击 Update 手动触发
• 用户就能执行 composer require myname/my-php-library:^1.0 了

常见失败：Composer 安装时提示 “Could not find package” 或 “No matching package found”

这不是 Packagist 同步延迟就是配置错位，优先排查这几项：

• 检查 Packagist 包页是否显示 Status: active，若为 inactive，说明首次抓取失败（常因 composer.json 缺 name 或格式不合法）
• 运行 composer clear-cache，再试 composer show myname/my-php-library —— 若仍报错，说明 Packagist 还没成功索引
• 确认本地 composer.json 中的 name 与 Packagist 上显示的完全一致（包括大小写和连字符）
• 如果你改过仓库地址（比如从 GitHub 迁移到 GitLab），需在 Packagist 删除原包并重新提交新 URL；Packagist 不自动迁移

最易被忽略的一点：Packagist 只认 HTTPS 克隆地址，如果你的 composer.json 里写了 "source": { "url": "git@github.com:..." }，它会跳过 source 类型镜像，但不影响基本安装 —— 不过调试时容易误判来源。

# php  # gitlab  # ai  # curl  # github  # composer  # json  # git  # js  # require