composer.json语法错误会导致安装失败，需用jq或PHP预检；语法合法不等于可用，须结合官方schema校验字段语义；validate --strict可检查语法、schema及弃用字段，CI和Git hook中应强制执行。
composer.json 文件语法错误会直接导致安装失败
Composer 在执行 composer install 或 composer update 前其实不主动校验 JSON 语法，而是等解析时才报错——这时候你看到的往往是类似 JSON decode error: Syntax error 这种模糊提示，实际问题可能只是少了个逗号或引号没闭合。
- 最快速定位：用系统自带的
jq工具做预检，运行jq '.' composer.json，如果输出结构化 JSON 就说明语法基本过关；报错则停在具体行号 - Windows 用户没有
jq？可用 PHP 自带 JSON 解析：运行php -r "json_decode(file_get_contents('composer.json')) or die('JSON error: '.json_last_error_msg());" - 别依赖 IDE 实时高亮——有些编辑器对
composer.json特有字段（如autoload的嵌套规则）不校验，只管括号配对
schema 校验比语法校验更重要
语法合法 ≠ Composer 能用。比如把 require 写成 requires，JSON 没毛病，但 Composer 会静默忽略该字段，最终依赖不装、自动加载失效，问题更难排查。
- 官方提供 JSON Schema：https://www.php.cn/link/ad0e1110d4470fa5d4b1481688337b26，可用于 VS Code、PHPStorm 等支持 schema 关联的编辑器
- 命令行校验推荐
jsonlint+ schema：安装后运行jsonlint --schema https://www.php.cn/link/ad0e1110d4470fa5d4b1481688337b26 composer.json - 注意版本差异：Composer 2.x 的 schema 不完全兼容 1.x，特别是
config下的platform和allow-plugins字段，老项目升级前务必核对
常见被忽略的字段约束
很多报错不是语法或 schema 层面的，而是字段值违反了 Composer 内部逻辑，比如版本号格式、路径存在性、脚本命令可执行性。
-
autoload中的psr-4映射路径必须是相对 vendor 目录的，且末尾要加/（如"App\": "src/"），写成"src"或"src/MyClass.php"都会加载失败 -
scripts里调用的命令，如果含空格或特殊字符（如php -d memory_limit=-1 ./vendor/bin/phpunit），需用数组形式写，否则 Composer 会截断 -
repositories类型为vcs时，url必须是可 git clone 的地址，不能是 GitHub 页面 URL（如https://github.com/user/repo错，应为git@github.com:user/repo.git或https://github.com/user/repo.git）
CI 中建议加一道静态检查
本地没问题，推到 CI 却失败？大概率是换环境后暴露了隐性问题，比如 Windows 换 Linux 后路径分隔符、大小写敏感、或 platform 配置与 CI 环境 PHP 版本冲突。
- GitHub Actions 可加一步：用
composer validate --strict，它会检查语法、schema、字段合理性（如是否用了已弃用字段），--strict是关键，否则默认跳过部分验证 - Git hook 也可提前拦截：在
.git/hooks/pre-commit里加入composer validate --no-interaction --strict，失败则拒绝提交 - 注意
composer validate不校验远程仓库可达性或包版本是否存在，那些得靠composer update --dry-run，但开销大，不适合每提交都跑
真正卡住人的往往不是 JSON 格式，而是字段语义理解偏差——比如以为 minimum-stability 设成 dev 就能装任意 dev 分支，结果发现还得配合 prefer-stable 和包自身的 stability 标签。这类细节，光靠校验工具发现不了。
