homepage字段仅作元数据展示，用于Packagist页面、“composer show”输出等处显示项目主页链接，不参与安装、解析、文档生成或部署，填错不影响功能但损害用户体验。

Composer 项目的 homepage 字段只影响 composer.json 元数据，不生成或托管任何网页，也不会自动发布到官方文档站点。

homepage 字段的用途和实际效果

它纯粹是元信息字段，用于在 Packagist、GitHub Composer 插件、composer show 输出中展示项目主页链接。Packagist 会抓取并显示该值，但不会校验有效性，也不参与文档构建流程。

• 不是文档生成入口：填了 "homepage": "https://example.com/docs" 不会让 Composer 自动部署文档
• 不影响安装行为：无论是否填写、填什么都对 composer install 或依赖解析零影响
• 不被 Composer 命令读取或使用：没有内置命令会基于它跳转或拉取内容

常见错误：把 homepage 当成文档发布配置

很多开源项目误以为设了 homepage 就等于“接入了官方文档系统”，结果发现链接打不开、文档没更新、甚至被误标为“无文档”。这通常是因为混淆了三个独立系统：

Expanso yaml-to-json

使用 Expanso Edge 管道将 YAML 输入转换为 JSON 格式。

下载

• Packagist（仅展示元数据）
• GitHub Pages / Read the Docs / VuePress 等（需单独配置构建与部署）
• Composer 自身（完全不处理文档）

典型错误示例："homepage": "https://myorg.github.io/mylib" —— 若未实际在 GitHub Pages 开启并部署文档，该链接就是 404。

正确关联文档的实操路径

若希望用户通过 Packagist 快速访问文档，必须手动完成两件事：

• 在项目仓库中搭建静态文档站点（如用 mkdocs + GitHub Pages，或 vuepress build 推送到 gh-pages 分支）
• 确保 composer.json 中的 homepage 指向已可访问的最终 URL（例如 "https://mylib.org"），且该域名或路径真实响应 HTTP 200
• 可额外补充 support.docs 字段（非必需，但部分工具识别）：

  "support": {
    "docs": "https://mylib.org/guide"
  }

为什么很多人卡在这里

因为 Composer 的文档生态是拼装式的：Packagist 不托管内容，GitHub 不运行构建，composer.json 只存指针。真正容易被忽略的是——homepage 必须指向一个你已经部署好、且长期维护的终端地址，而不是“计划中的”或“本地能跑通的”路径。一旦写进 composer.json 并提交到 Packagist，这个链接就成为项目对外的文档门面，失效即等于信息断连。