# Composer 包的 homepage 字段：你真的理解它的正确用途吗？ > 这个字段仅在 `composer show` 命令或 Packagist 页面中作为元数据显示，完全不影响包的安装、自动加载或功能发现。 ## 如何在 composer.json 中正确配置 homepage 字段 在 JSON 文件的根级别直接添加字符串字段即可，其值必须是有效的 URL 地址（建议使用 `https://` 协议）： ```json { "name": "vendor/package", "type": "library", "homepage": "https://example.com/my-package" } ``` 该字段没有任何验证机制，Composer 不会检查 URL 是否可访问，也不会进行重定向或解析操作。它本质上只是一个描述性字段。 - 仅影响 `composer show vendor/package` 输出结果中的 “Homepage” 行显示 - Packagist.org 页面会将此链接渲染为可点击的 “Homepage” 标签 - 如果省略此字段，Packagist 会尝试从 `source` 或 `dist` 的 URL 推断主页地址，但结果不可预测 - 不支持数组、对象或模板语法，只接受单个字符串值 ## homepage 与 repository、source、support 字段的核心区别 开发者经常混淆这几个字段，但它们的功能定位完全不同： - `repository`：告知 Composer 从何处获取包源代码（如 GitHub 仓库地址），在 `composer require` 安装时用于定位代码库 - `source` 和 `dist`：定义包的具体 Git 仓库地址或 ZIP 压缩包下载地址，通常由 Packagist 自动填充，手动修改通常无效 - `support`：包含 `issues`、`source`、`email` 等子字段，用于提供技术支持入口，Packagist 会单独展示为 “Support” 区块 - `homepage`：纯粹的展示性字段，与包的分发、加载、协作流程没有任何关联 ## 为什么设置了 homepage 字段却未在 Packagist 上显示 通常有三个主要原因，建议按以下优先级排查： 1. 未触发 Packagist 同步机制：推送到 GitHub 后，需确保 Packagist 已启用自动更新（Webhook 正常工作），或手动点击 “Update” 按钮 2. 分支未匹配默认设置：Packagist 默认只抓取 `main` 或 `master` 分支的 `composer.json` 文件，请确认修改的是默认主分支 3. 缓存延迟问题：Packagist 存在分钟级缓存，更新后等待 2-5 分钟再刷新页面；也可使用 `composer show -a vendor/package` 命令在本地验证是否已读取新字段 关键点在于：这个字段对依赖解析、自动加载、插件注册、脚本执行等核心功能完全无影响——它只是包名片上的网址链接，而非实际的门牌地址。不要指望通过它来引导用户或影响包的行为逻辑。