告别配置混乱：深度解析Composer.json核心字段最佳实践-composer-PHP中文网

name字段必须为小写、短横线分隔的两段式vendor/name格式，否则install立即失败；psr-4映射末尾反斜杠不可省略；classmap优先级高于psr-4；require-dev依赖可能引发ci环境版本冲突；config.platform仅伪报版本，不影响真实环境。

告别配置混乱：深度解析composer.json核心字段最佳实践

composer.json 不是填完就能跑的配置文件，字段顺序、约束写法、autoload 路径结尾符号这些细节，直接决定 composer install 是否失败、new MyClass() 是否报错、CI 是否凌晨崩在部署环节。

它不是“项目名”，而是 Composer 识别包的唯一 ID。写错就卡在第一步：

✅ 正确示例："name": "acme/blog-engine"、"name": "myorg/my-cli-tool"
❌ 常见错误："name": "MyBlog"（大写）、"name": "my_blog"（下划线）、"name": "123app"（数字开头）、"name": "acme/my-app/src"（带路径）
错误信息形如：Invalid package name "MyBlog": package names must be lowercase and consist of words separated by dashes.
本地测试也得守规矩——哪怕不发布到 Packagist，composer validate 也会校验它

PSR-4 的键是命名空间前缀，不是字符串拼接路径。少一个，自动加载器就找不到类：

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

✅ 正确："App\": "src/"、"Vendor\Package\": "lib/"
❌ 错误："App": "src/"（会尝试加载 AppFoo 而非 AppFoo）、"App\": "src"（路径没结尾斜杠，部分系统解析异常）
classmap 和 psr-4 共存时，classmap 条目优先匹配——哪怕同名类同时存在，也会加载 classmap 指向的那个文件
验证是否生效别只信 composer install 成功，要 composer dump-autoload -o 后实际 new AppFoo(); 测试

它只该装开发工具，但间接依赖可能和 require 冲突，而问题往往只在 --no-dev 场景暴露：

典型陷阱：require-dev 里加了 "phpunit/phpunit": "^10.0"，它拉入 symfony/console:^6.4；但 require 里已有 "symfony/console": "^5.4" ——本地 composer update 可能静默妥协，锁文件却记下 v6
CI 执行 composer install --no-dev 时，因锁文件残留 v6 版本，直接报 Your requirements could not be resolved
排查用：composer why-not symfony/console:5.4 查谁挡了路
CI 安装命令务必固定为：composer install --no-dev --prefer-dist，避免本地 vendor/ 状态干扰判断

它适合加载函数文件、常量定义或旧版无命名空间的类，但行为和 PSR-4 不同：

classmap 可指向目录（如 "classmap": ["src/functions/", "legacy/"]）或单个文件（如 "classmap": ["helpers.php"]）
扫描只在 composer dump-autoload 或 install/update 时触发，增删文件后不会自动更新 vendor/composer/autoload_classmap.php
漏掉这步，新函数文件根本不会被自动加载——别猜，直接 composer dump-autoload -o 再试
性能上，-o（optimize-autoloader）对 classmap 有显著提升，但对 PSR-4 效果有限；若全用 PSR-4，classmap-authoritative 可禁用 fallback 查找，进一步提速