Composer PHP包开发命名空间建议_Composer遵循PSR规范【开发】-composer-PHP中文网

PSR-4命名空间必须以结尾且不可与项目根命名空间重叠，否则导致类加载失败；需严格分离autoload与autoload-dev，修改composer.json后必须执行composer dump-autoload -o更新缓存。

composer php包开发命名空间建议_composer遵循psr规范【开发】

包开发时命名空间必须带末尾反斜杠，且不能和项目根命名空间重叠——否则用户安装后 Class not found 的第一反应永远是“你包写错了”，其实错在你没守住边界。

为什么包的 PSR-4 命名空间必须以结尾

Composer 解析 composer.json 里的 "MyPackage\": "src/" 是按字符串前缀匹配的。如果写成 "MyPackage"（无反斜杠），JSON 解析后就是字面量 "MyPackage"，导致 MyPackageHttpClient 被截成 HttpClient，最终去拼 src/Http/Client.php——但你的类实际在 src/Http/Client.php 下，路径对不上。

更隐蔽的问题是：不加反斜杠时，MyPackageFoo 也会被错误匹配，而它根本不是你的包。

"MyPackage\": "src/" ✅：正确声明命名空间前缀，匹配 MyPackageHttpClient 时只砍掉 MyPackage
"MyPackage": "src/" ❌：JSON 解析为纯字符串，匹配逻辑崩坏
"MyPackage": "src/" ❌：Windows 下易多打一个反斜杠，PHP 字符串解析会出错

包命名空间不能和用户项目共用前缀

假设你开发一个通用日志包，命名为 logger，却用 "App\": "src/" 作为 PSR-4 映射——那用户自己的 Laravel 项目也用 App，Composer 加载时就会混乱：到底是加载用户的 AppHttpControllerHome，还是你包里的 AppLoggerHandler？

PSR-4 按最长前缀优先，但用户项目通常比你的包更早执行 dump-autoload，结果你的类可能根本进不了自动加载表。

包命名空间应唯一、可识别，推荐格式：VendorNamePackageName（如 MonologLogger）
绝对不要复用常见项目前缀：App、Core、Http、Models
若包需提供“开箱即用”的类（如 Logger），应在顶层命名空间下放 Logger.php，对应 namespace VendorNamePackageName;，而非塞进 VendorNamePackageNameUtils

`autoload-dev` 不是可选项，而是隔离红线

测试类（如 TestsUnitLoggerTest）如果混进主 autoload，用户 composer install --no-dev 后仍会加载它们——不仅浪费内存，还可能因依赖未安装（如 phpunit）导致 Fatal error: Class 'PHPUnitFrameworkTestCase' not found。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

更严重的是，某些测试类里写了 class_alias() 或修改了全局状态，会污染用户运行时环境。

生产 autoload 只该包含真正对外暴露的类，路径严格限定在 src/ 或明确公开目录
autoload-dev 必须单独配置，且路径不能与 autoload.psr-4 重叠
CI/CD 中验证命令应含 composer install --no-dev --optimize-autoloader，确保生成的 autoload_psr4.php 不含测试代码

改完 `composer.json` 后必须跑 `composer dump-autoload -o`

很多人本地调试时只改 composer.json 就直接 require 'vendor/autoload.php'，结果报 Class not found。因为 vendor/autoload.php 实际读的是 vendor/composer/autoload_psr4.php 这个缓存文件，不是实时解析 JSON。

不加 -o 也能工作，但每次加载都要动态拼路径、检查文件是否存在；加了之后生成静态映射，跳过所有文件系统调用——尤其在 CI 环境或容器中，IO 慢得明显。