Packagist强制包名小写且严格匹配,命名空间须全小写、路径精确映射,版本依赖仅识别带v前缀的Git tag,PSR-4配置后需执行dump-autoload,契约接口必须置于require而非require-dev。

组件命名与命名空间必须严格匹配 Packagist 语义
Packagist 不接受纯数字、下划线开头或带空格的包名,且会强制将 vendor/name 转为小写。如果你注册了 MyCompany/LoggerBundle,实际在 Packagist 上显示为 mycompany/loggerbundle,而 Composer 安装时也只认小写形式。
常见错误现象:composer require MyCompany/LoggerBundle 报错 “Could not find package”,但 composer require mycompany/loggerbundle 成功;或本地开发时用大写命名空间 MyCompanyLogger,却在 composer.json 中配置 "psr-4": {"MyCompany\": "src/"},结果类加载失败——因为 PSR-4 映射不区分大小写,但文件系统(尤其是 Linux)区分。
- 统一使用小写字母 + 连字符(kebab-case)命名包,如
mycompany/logger-component - 命名空间必须与 vendor 名完全一致且全小写:
mycompanylogger,对应"psr-4": {"mycompany\logger\": "src/"} - 避免在命名空间中混用下划线或驼峰,PHP 自动加载器不解析它们
版本号必须严格遵循 SemVer 并绑定 Git Tag
Composer 解析版本依赖时,只信任 Git 标签(tag),而非分支名或提交哈希。若你在 composer.json 中声明 "mycompany/logger-component": "^1.2.0",Composer 会去 Packagist 查找该包所有符合 ^1.2.0 的 tag(如 v1.2.0、v1.2.5、v1.3.0),但不会拉取 release/1.2 分支或 main 上的最新代码。
容易踩的坑:开发者本地打 tag 用 git tag 1.2.0(缺 v 前缀),导致 Packagist 同步失败;或手动修改 composer.json 中的 "version" 字段,这字段被 Composer 忽略,纯属干扰项。
- 打 tag 必须带
v前缀:git tag v1.2.0,然后git push --tags - 确保每次 tag 对应一次完整的 CI 流水线验证(单元测试 + 静态分析 + 兼容性检查)
- 禁止在
composer.json中写"version": "1.2.0",该字段无实际作用
autoload 配置必须精确到子命名空间,且禁止跨目录映射
一个组件若同时提供核心逻辑和 Laravel 适配器,常见错误是把两者都塞进 src/ 并用单一 PSR-4 映射,比如:"psr-4": {"mycompany\logger\": "src/"}。这会导致 Laravel 用户安装后,自动加载器尝试加载 mycompanyloggerLaravelServiceProvider,但该类实际在 src/Adapters/Laravel/ 下——路径不匹配,类找不到。
正确做法是按功能边界拆分命名空间,并分别映射:
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
- 核心逻辑:映射
"mycompany\logger\": "src/Core/" - Laravel 适配器:映射
"mycompany\logger\laravel\": "src/Adapters/Laravel/" - Symfony 适配器:映射
"mycompany\logger\symfony\": "src/Adapters/Symfony/"
这样下游项目可按需加载,且避免因某框架适配器缺失导致整个包加载失败。
require-dev 里不能放运行时必需的“伪开发依赖”
有些团队习惯把 phpunit/phpunit、phpstan/phpstan 放在 require-dev,这没问题;但若把 psr/log 或 psr/cache 这类契约接口也放进 require-dev,就埋了雷——因为你的组件代码里 use PsrLogLoggerInterface,运行时必然需要该接口,但它不在 require 里,下游项目安装时就不会拉取,直接报 Class 'PsrLogLoggerInterface' not found。
判断依据很简单:只要你的 src/ 目录下任何 PHP 文件里写了 use 或 implements 或 extends 某个类/接口,它就必须出现在 require 中。
-
psr/*系列契约、symfony/polyfill-*、doctrine/annotations(若你用了注解)——全进require - 测试工具、构建脚本、IDE helper(如
phpdocumentor/reflection-docblock)——才进require-dev - CI 流水线中执行
composer install --no-dev后,仍能通过php -l和基础功能测试,才算合格
最易被忽略的点:组件发布后,Packagist 同步延迟可能长达数分钟,且不会通知你失败;如果 tag 推送后立刻在下游项目中 composer require,大概率命中缓存旧版本。务必等 Packagist 页面上显示新 tag 已索引完成,再验证安装。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










