Composer包发布需同时满足三条件：合规composer.json、可访问Git仓库、Packagist成功抓取tag；关键步骤包括规范配置name/type/autoload/require/license、打v前缀语义化tag并推送、在Packagist提交仓库URL、本地验证安装。

Composer 包不是“发布到 Packagist 就能用”，而是必须满足 composer.json 规范、有可访问的 Git 仓库、且 Packagist 能成功抓取 tag —— 缺一不可。

初始化项目并写好 composer.json

别直接 composer init 一路回车，它生成的默认配置对发布包几乎没用。你要手动确保以下字段存在且合理：

• name 必须是 vendor/name 格式（如 mygithub/my-awesome-package），且 vendor 和你在 Packagist 的用户名一致
• type 建议设为 library（非 project）
• autoload 必须定义，推荐 PSR-4：

  {
      "autoload": {
          "psr-4": {
              "MyAwesome\\": "src/"
          }
      }
  }

• require 只写真正运行时依赖；开发依赖（如 PHPUnit）放 require-dev
• 加 license 字段（如 "MIT"），否则 Packagist 会警告甚至拒绝索引

打 Git tag 并推送到远程仓库

Packagist 不读 main 或 master 分支的最新提交，只认 Git tag。你必须手动打语义化版本 tag：

• 先提交全部代码：git add . && git commit -m "feat: add hello world"
• 打 tag：git tag v1.0.0（注意 v 前缀，Packagist 默认识别这种格式）
• 推代码和 tag：git push && git push --tags
• 确认 GitHub / GitLab 页面能看到 v1.0.0 tag，且点击后能查看对应 commit

如果只推了代码没推 tag，Packagist 就抓不到任何版本，你会在包页面看到 “No releases found”。

在 Packagist 上提交仓库 URL

登录 Packagist → 点右上角 “Submit” → 粘贴你的 Git 仓库 HTTPS 地址（如 https://github.com/mygithub/my-awesome-package）→ Submit。

• 首次提交后，Packagist 会立即尝试抓取；若失败，会在包页显示错误原因（常见：Repository not found 权限问题，或 Invalid composer.json 格式错误）
• 成功后，它会自动监听新 tag：你后续 git push --tags，几秒到几分钟内新版就会出现在 Packagist 页面
• 不要勾选 “Auto-update” 以外的选项；如果仓库私有，Packagist 无法访问，必须用自建 Satis 或 Toran Proxy

本地测试安装是否真能用

别等别人反馈“装不上”，自己先验证：

• 新建测试项目：mkdir test-app && cd test-app && composer init -n
• 临时加你的包（不用等 Packagist 同步）：composer require mygithub/my-awesome-package:dev-main（用 dev-main 指向分支）
• 或者等 Packagist 同步完，直接：composer require mygithub/my-awesome-package:^1.0
• 检查 vendor/mygithub/my-awesome-package/src/ 是否存在，且 composer dump-autoload 后能正常 use MyAwesome\Hello;
• 关键陷阱：如果你的 autoload 指向 src/，但实际类文件放在 lib/，Composer 就不会加载任何东西，也不会报错 —— 只是静默失效

最常被忽略的是 autoload 路径与实际目录不匹配，以及忘记推 tag。这两个点卡住，Packagist 页面就永远是空的。