Composer description字段如何写_Composer包描述配置教程【实战】

Composer description字段如何写_Composer包描述配置教程【实战】

description 字段必须是纯字符串，不能写成数组或对象

一个常见的误区，是把 composer.json 里的 description 字段写成了多语言数组，比如 {“en”: “xxx”, “zh”: “yyy”}。这其实是无效操作。Composer 官方规范只认一个纯字符串值，其他任何格式都会被直接忽略，而且它不会给你任何错误提示——结果就是你改了也白改。

• 正确写法：“description”: “A lightweight HTTP client for PHP with PSR-7 support”
• 错误写法：“description”: {“en”: “…”, “zh”: “…”} 或 “description”: [“…”, “…”]
• 如果需要多语言支持，那得依赖 Packagist 网站的人工编辑功能或者第三方扩展，这并非 Composer 的原生能力。

description 会影响 Packagist 搜索结果和包页首屏可见性

这个字段可不是摆设。Packagist 在展示搜索结果和包详情页顶部时，会优先截取 description 的前120个字符左右（包含空格）进行展示，超出的部分就用省略号代替。关键是，它只展示纯文本，不解析任何 Markdown 语法，也不会渲染链接。

• 开头就要亮明核心功能，最好用动词开头，比如：“Sends HTTP requests”、“Validates email addresses”、“Generates UUIDs”。
• 避免堆砌无关关键词，也别写“PHP library for…”这种废话——Packagist 当然知道你这是 PHP 包。
• 不要把版本号、兼容性说明（比如 “for PHP 8.1+”）写在这里，这些信息应该放在 require 字段或者 readme.md 文件里。
• 反面教材：“description”: “My awesome package. It does things. Works with Lara vel.”
• 优秀范例：“description”: “PSR-18 compatible HTTP client with built-in retry, timeout, and JSON request/response handling”

description 和 README.md 不是互斥关系，但职责不同

千万别搞混了。description 是给机器和用户快速扫描用的元数据；而 README.md 才是面向开发者的完整文档入口。两者内容可以关联，但绝不能是简单的复制粘贴。

• 不要在 description 里写安装命令（比如 composer require vendor/name）、具体的用法示例或者配置说明。
• 也别引用外部链接（例如 “See https://example.com/docs”），因为 Packagist 不渲染链接，用户根本点不了。
• 如果你发现自己的包总搜不到，先检查一下 description 里是否包含了真实用户可能会搜索的“动词+名词”组合，比如 “csv parser”、“jwt decoder”、“redis lock”。

提交后 description 不会实时更新，需触发 Packagist 同步

这里有个容易踩的坑：你以为在 composer.json 里改好了 description 并推送到 GitHub，Packagist 就会立刻更新？其实不会。它依赖于 webhook 的触发或者手动操作。

• 首先，确认你的 GitHub 仓库已经在 Packagist 上正确绑定了（可以去 Packagist 包页面点击 “Edit” → “GitHub Hooks” 检查）。
• 如果没有启用 webhook，那就需要手动点击 Packagist 包页面右上角的 “Update” 按钮（需要登录且有相应权限）。
• 同步成功后，页面 URL 末尾的 commit hash 会发生变化，并且 “Last updated” 的时间也会刷新。
• 注意：通常只有推送新的 tag 或者更新默认分支，才会触发自动同步（具体取决于你在 Packagist 上的设置）。

说到底，Packagist 对 description 字段的处理方式非常“朴素”——不校验长度，不检查语法，也不索引标点，仅仅做一个简单的字符串截取和展示。最容易出问题的地方，恰恰是开发者误把它当成了 README 的摘要来写，而忘记了它本质上是一个独立的、面向搜索和第一印象的“广告语”。