composer.json是项目依赖契约而非普通配置文件，写错字段会导致装错包版本或class not found；require放运行时依赖，require-dev放开发工具；autoload需严格匹配命名空间与路径；minimum-stability和prefer-stable控制版本稳定性；scripts仅作轻量钩子，部署逻辑应独立。
composer.json 不是“可有可无的配置文件”，它是 Composer 安装、更新、自动加载行为的唯一事实来源——改错一个字段，composer install 就可能装出完全不同的包版本，甚至导致 Class not found 或 PHP Fatal error: Uncaught Error: Class 'X' not found。
require 和 require-dev 放错位置，上线就出事
这两个字段直接决定哪些包会进生产环境：require 里的包在 composer install --no-dev 下仍会被安装；require-dev 里的则被跳过。
-
require只放运行时真正依赖的包，例如"monolog/monolog": "^3.0"、"php": ">=8.1"—— 缺它，代码直接报错 -
require-dev放开发期工具：测试（"phpunit/phpunit": "^10.5"）、格式检查（"php-cs-fixer/php-cs-fixer": "^3.54"）、生成器等 - 常见错误：把
symfony/console塞进require-dev，结果命令行脚本在生产环境跑不起来——因为它实际被你的bin/下入口调用了 - 别用
"*"或"dev-main"写进生产依赖，稳定性不可控；默认minimum-stability是stable，但若没显式设prefer-stable: true，仍可能装到-beta版本
autoload 配错，class 就永远找不到
PSR-4 是现代 PHP 项目唯一推荐的自动加载方式，但它对路径、命名空间、大小写三者严格一一对应。
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
"psr-4": {"App\": "src/"}要求：src/Http/Controller.php必须以namespace AppHttpController;开头（注意双反斜杠转义） - 路径末尾不加
/会静默失败；命名空间末尾多一个（如"App\"写成"App"）会导致 JSON 解析失败 - 改完
autoload后必须手动执行composer dump-autoload，否则 vendor/composer/autoload_psr4.php 不更新，类依然找不到 - 老项目混用
classmap时，记得加"classmap": ["legacy/"]并定期运行composer dump-autoload --optimize生成静态映射
repositories 和 config.platform 不是“高级选项”，而是部署底线
镜像源和平台模拟直接影响依赖能否装上、装得对不对。
- 国内项目务必配国内镜像，否则
composer install极易超时失败：composer config repo.packagist composer https://packagist.laravel-china.org -
config.platform用于锁定目标运行环境能力，比如线上是 PHP 8.2 但本地是 8.3，不加"platform": {"php": "8.2.10"}就可能装入仅兼容 8.3 的扩展函数 - 私有包必须通过
repositories显式声明类型和地址，类型为vcs时 URL 必须是 Git 仓库地址（如https://gitlab.example.com/myorg/mylib.git），不是网页链接 - 别在
repositories里留已废弃的源（如packagist.phpcomposer.com已停服），会导致整个依赖解析卡死
scripts 字段不是 shell 脚本替代品
scripts 是 Composer 生命周期钩子的触发点，不是通用命令封装区。
- 只适合轻量、与依赖强相关的动作：如
"post-autoload-dump": "php scripts/build-constants.php" - 禁止放部署逻辑（如 rsync、数据库迁移）——这些该由 CI/CD 流水线或独立 deploy 脚本负责
- 自定义脚本名（如
"build"）需用composer run build调用；内置事件名（如pre-install-cmd）会自动触发，但滥用会影响composer update稳定性 - 脚本中调用其他 Composer 命令（如
composer dump-autoload）要加--no-interaction，否则在 CI 环境会卡住
composer.json 里没有“看起来差不多就行”的字段。每一个键值对都在参与构建真实运行时环境——尤其是 autoload 的命名空间路径映射、config.platform 对 PHP 版本的锁定、以及 repositories 源的可用性，这三点最容易在线上突然失效，且排查时往往绕半天才回到 composer.json 本身。
