如何通过Composer开发并创建一个自定义的软件包？

本文共计877个文字，预计阅读时间需要4分钟。

能被 + composer require 正常安装的包，90%+ 的问题出现在 + composer.json + 配置和自动加载规则上，而不是代码本身。

composer.json 必须满足这 4 个硬性条件

Packagist 不是“看到 GitHub 仓库就收录”，它只认 composer.json 里几个关键字段是否合规：

• name 必须是 vendor/name 格式（如 myorg/http-client），不能是 http-client 或 MyOrg/HttpClient（大小写敏感、斜杠位置固定）
• type 显式设为 library，否则可能被当 project 或 metapackage 过滤掉
• autoload 必须显式声明，哪怕只用 PSR-4：

  { "autoload": { "psr-4": { "MyOrg\HttpClient\": "src/" } } }注意命名空间末尾双反斜杠和路径结尾斜杠都要有

• license 字段不可省略，填 "MIT" 最稳妥；Packagist 强制校验该字段，缺了直接拒收

为什么 composer require 找不到你的包

不是 GitHub 地址错了，而是 Packagist 没同步或没权限抓取：

• 首次发布必须手动去 https://www.php.cn/link/20a1f94e0e45384e8e08872de5a5e545 提交仓库 URL，没有“自动发现”这回事
• 确保 GitHub 仓库是公开的；私有仓库需提前配置 composer config --global github-oauth.github.com <token>
• 改过 name 后本地缓存会卡住——删掉主项目里的 vendor/ 和 composer.lock，再运行 composer clear-cache
• 错误信息里出现 Could not parse version constraint？大概率是 composer.json 里写了死版本号 "version": "1.0.0"，删掉它，版本靠 Git tag 控制

本地开发时怎么边写边测，不发版也能 require

别反复 push → 等同步 → composer update，太慢。用 path 类型仓库：

• 在主项目 composer.json 的 repositories 里加一段：

  "repositories": [ { "type": "path", "url": "../my-http-client" } ]

• 然后执行 composer require myorg/http-client:dev-main（注意用实际分支名，不是 dev-master）
• 改完包代码后，在主项目里只需 composer update myorg/http-client，无需提交、打 tag
• 切记：path 方式仅限开发，上线前必须删掉该 repositories 条目，否则部署环境会找不到路径

自动加载是否真生效？必须验证

很多人配完 PSR-4 就以为万事大吉，但 Composer 不会主动告诉你映射失败：

• 运行 composer dump-autoload -o 强制重生成优化 autoload 文件
• 再执行 composer show myorg/http-client，看输出里是否明确列出 autoload 路径（比如 psr-4 MyOrg\HttpClient\ => src/）
• 如果没显示，或者提示 Package not found，说明 name 不匹配或路径写错，不是代码没加载，是根本没注册进 Composer 的包索引

最常被跳过的一步是验证 autoload 是否真正注册成功——composer show 的输出比 require 不报错更有说服力，因为后者可能只是碰巧加载了其他同名类。