composer如何配置项目的readme文件路径_composer.json字段说明【详解】

composer 不支持自定义 README 路径，因其硬编码只识别根目录下 README、README.md 等固定命名文件；composer.json 规范中不存在 readme 字段，Packagist 通过 git 克隆读取根目录匹配文件，不解析该字段，也不支持子目录或符号链接。

Composer 不支持通过 composer.json 配置自定义 README 文件路径 —— 它只会自动识别项目根目录下的 README、README.md、README.rst 等常见命名，且该行为由 Packagist 和 Composer 自身硬编码决定，无法通过字段修改。

为什么没有 readme 字段？

Composer 的 composer.json 规范中**不存在 readme 字段**。Packagist（及大多数 Composer 仓库）在抓取包信息时，直接按固定优先级列表扫描根目录文件：

• README.md（最常用）
• README.rst
• README（无后缀）
• README.txt

即使你在 composer.json 里手动加一个 "readme": "docs/intro.md"，Composer 命令（如 composer install）和 Packagist 都会完全忽略它。

packagist.org 显示 README 的真实逻辑

Packagist 在同步包时执行的是 Git 克隆 + 文件读取，不是解析 composer.json。它：

• 只看 Git 仓库根目录 下的匹配文件（不递归子目录）
• 对大小写敏感（Readme.md ≠ README.md，后者才被识别）
• 不支持符号链接或生成式文件（如通过 make readme 生成的临时文件，若未提交到 Git 则不可见）
• 缓存可能延迟：改完 README 后需触发 Packagist 重新抓取（如推送新 tag 或手动 sync）

想用非根目录的 README？只能间接处理

如果你必须把文档放在 docs/README.md 或类似路径，可行但有限的绕过方式有：

• 在项目根目录放一个极简 README.md，内容仅为：

  See detailed documentation in [docs/README.md](docs/README.md).

• 使用 scripts 在 post-install-cmd 或 post-update-cmd 中自动复制或软链：

  "scripts": {   "post-install-cmd": [     "ln -sf docs/README.md README.md || copy docs\\README.md README.md"   ] }

  （注意：windows / unix 路径差异、权限、CI 环境是否允许执行 shell 命令）

• 放弃 Packagist 自动渲染，改用 github/gitlab 页面直接展示（它们各自支持自定义 README 路径，但和 Composer 无关）

真正需要控制文档入口的场景，往往已超出 Composer 的职责边界——它管依赖与包元数据，不管文档托管。别在 composer.json 里找不存在的字段，也别指望靠改配置让 Packagist 去读 src/README.md。