keywords 字段直接影响 Packagist 网站的搜索结果排名，是显式匹配依据；需用小写英文单词、聚焦功能词、覆盖同义词与技术栈标签，控制在3–8个，避免泛义词、空格、大小写混乱或JSON格式错误。
keywords 字段到底影响什么搜索行为
keywords 是 Packagist 搜索算法的显式匹配依据之一，不是装饰字段。它不参与依赖解析、自动加载或安装流程，但直接决定你的包能否在 packagist.org 上被“搜出来”。比如用户搜 csv，即使你的包名叫 data-exporter 且描述里没提这个词，只要 keywords 包含 "csv"，就大概率出现在第一页结果里。
怎么写 keywords 才算有效
无效关键词 = 白写。以下做法能真正提升可发现性：
- 用小写英文单词，不带空格、不加引号、不混用大小写（
"JWT"不如"jwt"） - 聚焦功能词：如
"validation"、"middleware"、"psr-7"，而不是"php"或"library" - 覆盖同义词和常用缩写：比如同时写
"auth"和"authentication"，因为不同开发者输入习惯不同 - 带上技术栈标签：如果是 Laravel 专用包，
"laravel"必加；是 Symfony Bundle，就加"symfony-bundle" - 控制在 3–8 个之间：太少覆盖不足，太多会稀释权重，Packagist 不会优先展示堆砌关键词的包
常见错误配置及后果
这些写法看似合理，实则让 keywords 失效：
- 写成字符串而非数组：
"keywords": "cache, api"→ JSON 格式错误，composer validate会报错 - 包含空格或特殊字符：
"keywords": ["laravel package"]→ 实际只被当作一个词"laravel package"，无法匹配单独搜laravel的用户 - 用泛义词或营销话术：
"awesome"、"best"、"php-library"→ Packagist 过滤掉这类低信息量词，且损害专业感 - 拼写错误或大小写混乱：
"UUID"或"Uuid"→ 搜索uuid时不会命中（Packagist 搜索默认小写归一化） - 漏掉核心场景词：比如一个 Markdown 解析器没加
"markdown-parser"，只写了"html"和"string"→ 用户根本找不到你
验证是否生效的实操步骤
改完 composer.json 不等于立刻生效，必须触发 Packagist 抓取更新：
- 打新 tag（如
v1.2.0）或 push 到默认分支（通常是main），Packagist 通常 2–5 分钟内自动同步 - 打开你的包页面（
https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0packages/your-vendor/your-package），确认右侧 Keywords 区域已更新 - 在 Packagist 搜索栏分别输入每个 keyword，观察你的包是否出现在前 3 页；若无，检查是否拼写一致、是否被其他更热门包压制
- 对比同类高星包的
keywords（如guzzlehttp/guzzle或monolog/monolog），看它们用了哪些你遗漏的通用术语
最常被忽略的一点：keywords 单独作用有限，它必须和 description（首句嵌入 1–2 个核心词）、type（如 "laravel-package"）、甚至 extra.laravel 配置协同，才能在特定生态中真正“冒头”。
