description 字段是 composer.json 中唯一被官方认可且具实际用途的备注位置，用于显示项目说明，不参与依赖解析；其他位置添加备注易引发维护和解析问题。
Composer 的 composer.json 文件本身不支持“备注”字段，但可以用 description 字段替代，它会被 Packagist 显示，也能被 IDE 和工具识别为项目说明。
description 字段是唯一标准的“备注”位置
很多人想加注释或内部备注，比如“这个包只用于测试环境”，但 composer.json 是 JSON 格式，不支持注释（// 或 /* */ 会直接报错）。唯一被 Composer 官方认可、且有实际用途的描述字段就是 description：
- 必须是字符串类型，建议控制在 120 字以内（Packagist 截断显示）
- 不是元数据字段，不会影响依赖解析或安装行为
- IDE（如 PHPStorm）会在
require列表里 hover 显示该描述 - 执行
composer show vendor/package时会输出该字段
示例：
{
"name": "myorg/my-tool",
"description": "CLI 工具，用于批量重命名本地图片文件（仅限 v3.2+）",
"type": "library",
"require": { ... }
}别往 extra 或 scripts 里塞“伪备注”
有人把备注写进 extra 或 scripts，比如：
"extra": {
"note": "上线前记得删掉 mock 依赖"
}这看似可行，但实际带来问题：
-
extra是给第三方插件用的，你的note不会被任何标准工具读取或展示 - 容易和真实插件配置（如
laravel/framework的laravel子键）混淆，后期维护难判断意图 - CI/CD 脚本若遍历
extra，可能误读你写的“备注”为配置项 -
scripts里塞echo类命令看似能提示，但只在运行时生效，且污染脚本列表
如果真需要内部说明，改用 .gitattributes 或 README.md
JSON 不支持注释，硬加只会让 composer validate 失败。真有团队协作所需的上下文说明，更稳妥的做法是：
- 在项目根目录放
README.md，写清特殊依赖原因、版本约束逻辑、已知限制 - 用
.gitattributes标记composer.json为 `merge=union`，避免多人修改时丢失关键字段（虽然不解决备注，但降低误操作风险） - 如果必须嵌入机器可读的额外信息，考虑用独立的
composer.meta.json（非标准，需自行约定并文档化），而不是污染主配置
真正起作用的只有 description；其他地方写的“备注”，不是被忽略，就是埋了后续解析或协作的雷。
