description字段是纯文本元信息，仅用于packagist页面、composer show输出和ide提示，不参与依赖解析；需以动词开头，含技术锚点，120字内精准传达功能、对象与约束。
Composer 的 description 字段不是技术配置项，而是纯文本元信息，不参与安装、解析或依赖逻辑 —— 它只在 Packagist 页面、composer show 输出和 IDE 提示里可见，写得模糊或空着，不影响包运行，但会显著降低被发现和被信任的概率。
description 字段的真实作用场景
它不是给 Composer 解析用的，是给人看的。Packagist 搜索结果页第一眼看到的就是这个字段；运行 composer show vendor/package 时，它紧挨着版本号显示；某些 IDE（如 PHPStorm）在 require 补全时也会抓取它作提示文案。
- 搜索匹配：Packagist 会对
description做全文检索，关键词（如 “Laravel”, “validation”, “async”）写在里面才容易被搜到 - 信任建立：空着、写 “A PHP package” 或堆砌 SEO 词（如 “best fastest awesome library”），会让人立刻跳过
- 上下文补充：如果包名本身不表意（比如
vendor/bridge），靠 description 交代角色，例如 “HTTP client adapter for Guzzle → PSR-18 bridge”
怎么写才有效：三条硬约束
不是写作文，是写“功能标签 + 使用对象 + 关键约束”的紧凑短句。Packagist 界面只显示前 120 字左右，截断后还必须能独立传达价值。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 开头必须动词起手，说明「做什么」：
Generates PDFs from HTML using Chromium，而不是A PDF generator... - 包含一个明确的技术锚点：框架（
Laravel）、标准（PSR-14）、协议（OAuth2）或工具链（PHP 8.2+） - 避免主观形容词和空泛表述：
robust、modern、lightweight全部删掉；不写for developers（谁不是开发者？）
✅ 好例子：Validates email addresses using DNS and SMTP probes, compatible with Symfony Validator
❌ 坏例子：A lightweight, modern, and robust email validation library for PHP developers
常见填坑点：description 不生效？不是 bug，是缓存或配置错
Packagist 不实时拉取 composer.json，也不是所有字段都进索引。如果改了 description 却没更新，先排查这几个地方：
- Packagist 未同步：改完
composer.json后，需手动触发更新 —— 进入 Packagist 对应包页，点Update按钮（或等 webhook 自动触发） - 字段位置错误：确保
description是根级键，和name、type并列，不在extra或autoload里 - 值类型错误：必须是字符串，不能是
null、array或带换行的多行字符串（JSON 不支持裸换行） - 私有包无展示：若包未提交到 Packagist（比如只在私有 Satis 或 Artifactory），
description只在本地composer show可见，外部不可见
真正难的不是语法，是用 15 个词说清“谁在什么场景下用它解决什么问题”。很多人花两小时调 autoload，却用两秒随便填 description —— 而用户决定点不点进去看 README，就在这 15 个词里。
