composer中如何配置项目的readme文件名映射_composer.json非标准文件配置【教程】

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.md
• README.rst
• README.txt
• README

这个顺序不可配置，也不读取 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 仓库根目录下真实存在的、符合命名顺序的文件——别的都是徒劳。