Composer 不支持自定义 README 文件名映射，Packagist 按 README.md→README.rst→README.txt→README 顺序取首个存在文件展示，忽略 composer.json 中任何 readme 字段；唯一可靠方案是创建指向自定义文档的符号链接 README.md。
Composer 不支持自定义 README 文件名映射，composer.json 中没有对应字段；所谓“README 映射”是第三方平台（如 Packagist）的解析逻辑，不是 Composer 本身行为。
Packagist 如何识别 README 文件
Packagist 在抓取包信息时，会按固定顺序查找以下文件名，并取第一个存在的内容作为包的描述展示：
README.mdREADME.rstREADME.txtREADME
这个顺序不可配置，也不读取 composer.json 的任何字段。即使你写 "readme": "INTRO.md"，Packagist 完全忽略。
为什么 composer.json 没有 readme 字段
Composer 的核心职责是依赖管理与自动加载，不负责文档渲染或元数据展示。它只关心：name、version、autoload、require 等运行时必需字段。
- 官方 schema 中不存在
readme字段，添加后会导致composer validate报警告（非错误，但属无效键） - IDE 和工具链（如 PhpStorm、VS Code 插件）也不会读取该字段
- 某些私有仓库管理器（如 Satis、Private Packagist）同样沿用 Packagist 的 README 查找逻辑
想用非标准名（如 DOCS.md）怎么办
唯一可靠方式是**符号链接 + 标准名共存**，兼顾工具兼容性与项目习惯：
ln -sf DOCS.md README.md
这样既满足 Packagist 的硬性查找规则，又保留源文件语义清晰。注意：
- 确保 Git 跟踪
README.md符号链接（Linux/macOS 默认跟踪；Windows 需git config --global core.symlinks true） - 不要用 Windows 快捷方式（.lnk），它不被 Git 或 Packagist 识别
- 避免在
.gitignore中忽略README.md，否则 Packagist 抓不到
常见误解与踩坑点
有人尝试在 composer.json 中写：
{
"extra": {
"readme": "CHANGES.md"
}
}
这不会生效。原因：
-
extra是供插件或自定义脚本读取的自由区，Packagist 不解析它 - 目前没有任何主流 Composer 插件约定读取
extra.readme - 若自行写脚本处理，需在
post-install-cmd或post-update-cmd中手动复制/生成README.md，但无法影响 Packagist 抓取结果
真正影响 Packagist 展示的，只有 Git 仓库根目录下真实存在的、符合命名顺序的文件——别的都是徒劳。
