composer run-script必须严格匹配composer.json中scripts顶层键名，大小写、空格、冒号均不可错；含冒号脚本名Windows下须加双引号；参数须用--分隔；PHP脚本需手动引入autoload.php。
脚本名必须严格匹配 composer.json 里的键名
拼错一个字母、多一个空格、大小写不一致，composer run-script 就会报 Script not found。它不模糊匹配，也不自动补全。
常见错误现象：composer run-script dev:start 报错，但你确实在 composer.json 里写了 "dev:start"——大概率是 Windows CMD 下没加双引号，或冒号被 shell 当作命令分隔符吃掉了。
- Windows 用户必须用双引号包裹含冒号的脚本名：
composer run-script "dev:start" - 运行
composer run --list（推荐）或composer run-script --list查看实际注册的脚本，没出现在列表里就等于没生效 -
"scripts"必须是composer.json的顶层字段，不能缩进在"require"或"autoload"里面
参数必须用 -- 显式分隔，否则被 Composer 吞掉
composer run-script test -- --filter=MyTest 中间那个 -- 不是可选的，是硬性分隔符。漏掉它，--filter=MyTest 就会被 Composer 当作自己的参数处理，最终传给 phpunit 的是空参数。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 错误写法：
composer run-script test --filter=MyTest（Composer 报错或静默忽略） - 正确写法：
composer run-script test -- --filter=MyTest - 如果脚本本身是 shell 命令，注意引号嵌套，比如：
"lint": "php -l \"src/MyClass.php\""
PHP 脚本不自动加载 autoload，必须手动 require
直接在 scripts/deploy.php 里写 new App\Services\Deployer()，会报 Class not found——不是路径错了，是 Composer 根本没加载 autoloader。
- 第一行必须加：
require __DIR__ . '/../vendor/autoload.php'; - 别用
include 'vendor/autoload.php'（相对路径不可靠） - 别依赖
$_ENV或getenv()读环境变量——CLI 下默认为空，得显式putenv('APP_ENV=prod')，或用symfony/dotenv - 更稳妥的调用方式是：
"deploy": "@php scripts/deploy.php"，@php前缀会自动使用 Composer 绑定的 PHP 版本
别把复杂逻辑塞进 scripts 字段
看到 "build": ["rm -rf build/", "mkdir build", "cp -r src build/"] 这种写法就该警觉——它在 Linux/macOS 下能跑，Windows CMD 下基本全跪；而且没法做条件判断、异常捕获、日志记录。
- shell 命令跨平台兼容性差、错误难捕获、参数解析弱
- 真正稳定的自定义逻辑应该写成独立 PHP 文件（如
scripts/build.php），然后在scripts中调用 - 脚本名不能和 Composer 内置命令冲突（如
install、update），否则会被覆盖且无警告 - 多个命令用分号连接（
"cmd1; cmd2"）在 Windows 上可能失败，建议改用symfony/console封装
复杂点在于：脚本执行时当前工作目录（CWD）固定为 composer.json 所在目录，且默认不继承 shell 的 $PATH 和 .env；这些细节在本地能跑、CI 报错时最容易被忽略。
