Composer validate 不报 description 缺失,因为 schema 中 description 是可选字段,空字符串或缺失均通过校验;Packagist 虽不拒收但搜索权重低,下游工具依赖该字段。

Composer 不会自动检测 composer.json 中缺失的描述字段,它只在执行特定命令(如 validate 或发布到 Packagist)时做基础 schema 校验,且默认不检查字段语义完整性(比如 description 是否为空或缺失)。
为什么 composer validate 不报 description 缺失
Composer 内置的 JSON Schema 验证只强制要求 name 和 version(对库包)或 type(对项目),description 是可选字段,即使完全没写或写成空字符串 "description": "",composer validate 也默认通过。
- schema 定义在 Composer 源码的
res/composer-schema.json中,description的"required"数组里未包含它 - 空字符串被视为合法值 —— 这和“缺失”在 JSON 层面不同,但实际效果一样:Packagist 会显示 “No description”
- 如果你用
composer validate --strict,它仍不会检查字段内容,只加强格式/引用类校验(如 autoload 路径是否存在)
用 jq 快速批量检查 description 是否缺失或为空
适合 CI 脚本或本地预检,直接读取 composer.json 并判断字段状态:
jq -e 'if (.description | type == "string") then .description | test("^\s*$") else true end' composer.json
返回非零退出码即表示 description 缺失或纯空白。更实用的写法是:
jq -e '.description | select(type != "string" or test("^\s*$"))' composer.json >/dev/null
- 返回 0 → 有问题(缺失或为空),可配合
|| echo "Missing or empty description" - 注意:不要依赖
jq的has("description")单独判断,因为"description": null也会被has()认为存在 - CI 中建议加在 pre-commit hook 或 GitHub Actions 的
on: pull_request步骤里
用自定义 PHP 脚本做语义级校验(推荐用于团队规范)
Composer 原生不提供钩子,但你可以写一个轻量脚本,在 composer install 前或 CI 中运行:
<?php
$json = json_decode(file_get_contents('composer.json'), true);
if (!isset($json['description']) || !is_string($json['description']) || trim($json['description']) === '') {
fwrite(STDERR, "ERROR: 'description' is missing or empty in composer.json
");
exit(1);
}
?>
- 比
jq更易集成进现有 PHP 工作流(比如用composer run-script绑定) - 能自然复用 Composer 的 autoloader(如果需要后续解析其他字段)
- 注意:避免在
autoload-dev里注册该脚本,否则可能污染开发环境自动加载
真正容易被忽略的是:Packagist 在抓取包时,如果 description 为空,它不会拒绝收录,但搜索权重极低,且所有下游工具(如 dependabot、phpinsights)都依赖这个字段做上下文提示 —— 所以“不报错”不等于“没问题”。


















