如何设置Composer包的主页地址？

本文共计768个文字，预计阅读时间需要4分钟。

json{ repositories: [ { type: composer, url: https://example.com/repo } ]}

homepage 字段必须放在根级，不能塞进 extra 或 config

它和 name、description 同级，不是子字段。Packagist 只认顶层的 homepage，其他位置一律忽略。

• ✅ 正确：

  { "name": "vendor/package", "description": "A useful lib", "homepage": "https://mylib.dev" }

• ❌ 错误："extra": { "homepage": "https://..." }、"config": { "homepage": "..." }
• ⚠️ 空字符串 "" 或 null 被视为未填写，Packagist 显示 “No homepage”

值必须是合法 URL，相对路径和缺协议都会失效

Packagist 不校验格式，但浏览器点击时会出错：缺协议变成相对跳转，相对路径直接 404。

• ✅ 可用："https://mylib.dev"、"https://github.com/user/repo#readme"
• ❌ 无效："mylib.dev"（没协议）、"./docs"（相对路径）、"git@github.com:user/repo.git"（SSH 地址）
• ? 如果没独立站点，指向 GitHub README 是可接受的底线，但别填 https://packagist.org/packages/... 这种循环链接

改了为什么 Packagist 没更新？同步不是自动的

Packagist 不轮询你的仓库，它只在特定事件触发时拉取最新 composer.json。

• ✅ 有效触发方式：推送到默认分支（如 main）、打新 tag（git tag v1.2.3 && git push --tags）
• ✅ 手动点 Packagist 页面右上角的 “Update” 按钮（需登录且有权限）
• ⚠️ webhook 失效、分支名非默认、composer.json 不在仓库根目录，都会导致同步失败
• ? 验证是否生效：运行 composer show vendor/package | grep homepage，或看 Packagist 页面右上角 “Homepage” 按钮是否可点击

homepage 和 repository、support.source 别混用

三者语义不同，Packagist 分别展示为 “Homepage”、“Source”、“Repository” 按钮，填反了用户点进去就错位。

• ✅ homepage：面向用户的官网或文档首页（如 "https://mylib.dev"）
• ✅ repository：代码托管地址（如 "https://github.com/vendor/package"），Composer 安装依赖时实际使用它
• ✅ support.source：单独定义 “Source” 标签内容，优先级高于 repository；若想让 “Source” 指向 GitHub，应写在这里而非 homepage
• ⚠️ 把 repository 复制给 homepage，用户点 “Homepage” 就跳进代码页，体验割裂

真正容易被忽略的是：这个字段对 Composer 运行时零影响，但它一旦发布到 Packagist，就成了下游用户接触项目的第一入口——链接 404 或指向错误页面，比修复一个 bug 更难追溯和修复。