Packagist 完全忽略 homepage 字段，仅用于用户点击跳转；应填公开可访问、长期稳定的项目官网/Git 仓库/文档站 URL，避免短链、参数、空格或未编码中文。
homepage 字段填什么才被 Packagist 正确识别
Composer 的 homepage 字段本身不参与包注册逻辑，Packagist 完全忽略它——它只读取 source（如 Git 仓库地址）和 type，再配合 name 做唯一性校验。填错链接不会导致发布失败，但会影响用户点击“Homepage”跳转时的体验。
常见错误现象：homepage 指向一个 404 页面、临时测试域名、或内部 Wiki 链接；有些开发者误填成 Packagist 包页 URL（如 https://packagist.org/packages/vendor/package），这反而会让使用者绕过你的真实文档站。
- 必须是公开可访问、长期稳定、与项目强相关的网址
- 优先级顺序：项目官网 > GitHub/GitLab 仓库首页 > 专属文档站（如
https://package.example.com） - 避免使用带查询参数的 URL（如
?ref=packagist），部分镜像站或 IDE 插件会截断参数 - 不要用短链服务（bit.ly、t.co 等），它们可能失效，且 Packagist 不做重定向解析
composer.json 里 homepage 和 support.source 的区别
homepage 是单个主入口，support.source（在 support 对象下）才是 Packagist 解析并展示为 “Source” 标签的字段。如果你希望用户点“Source”跳到 GitHub，必须把仓库地址写进 support.source，而不是 homepage。
示例对比：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"homepage": "https://example.com/my-package",
"support": {
"source": "https://github.com/vendor/my-package"
}
}
这样 Packagist 页面才会显示“Source: github.com/vendor/my-package”，而顶部“Homepage”按钮跳转到你的官网。
-
homepage影响 IDE（如 PHPStorm）悬停提示里的链接位置 -
support.source决定 Packagist “Source” 标签内容，也影响composer show -s vendor/package输出 - 两者可以不同，但不能互换用途；填反了，用户点“Source”会进官网，点“Homepage”却进了 GitHub，体验割裂
私有包要不要写 homepage
要写，但得写对地方。私有包不发布到 Packagist，所以 homepage 不会被公开索引，但它仍被本地工具链消费：CI 脚本可能用它生成报告链接，内部文档系统可能自动抓取该字段生成依赖图谱，PHPStan/PHPMD 的某些插件也会读取它做元信息校验。
- 指向内网 Confluence / Notion 文档页时，确保 CI 机器能解析该域名（DNS 和网络策略）
- 如果用 GitLab 私有实例，
support.source应填完整 HTTPS 仓库地址（含.git后缀），否则某些自建 Satis 服务无法 clone - 避免写
localhost或127.0.0.1—— 这类值在容器化部署或远程 CI 中必然失败
homepage 值含空格或中文会出问题吗
会，但不是 Composer 报错，而是下游工具链出问题。Composer 自身只做 JSON 解析，允许任意 UTF-8 字符；但 Packagist 前端、某些 IDE 插件、或旧版 cURL（如 CentOS 6 默认版本）在处理含空格或未编码中文的 URL 时，可能直接截断或 400 错误。
- 绝对不要手动拼接带空格的路径，比如
"https://example.com/my package" - 中文域名必须用 Punycode 编码（如
https://xn--fiq228c.com），不要直接写https://你好.com - URL 中的路径部分如有特殊字符（如
?、#），务必用urlencode处理，或改用更简洁的静态路径
真正麻烦的不是写错，是写对了但没人检查它是否真能打开——上线前用 curl -I 或浏览器隐身窗口点开一次，比任何文档都管用。
