GitHub 的 URL 为什么会变长
GitHub 的 URL 由所有者名、仓库名、分支名和文件路径等拼接而成。例如,指向特定文件特定行的永久链接会变成这样:
`github.com/organization/repository-name/blob/a1b2c3d4e5f6/src/components/authentication/LoginForm.tsx#L42-L58`
Issue 或 Pull Request 评论的链接也会附带 `#issuecomment-1234567890` 这样的片段标识符,因此会变得更长。代码审查的差异链接更是文件路径和哈希值的组合,也有超过 200 个字符的情况。
将这些长 URL 粘贴到 Slack 的消息串或邮件中,消息的相当一部分会被 URL 占据,变得难以阅读。
git.io 停用后的替代方案
README 中的短链接应用
GitHub 仓库的 README 是作为项目门面的文档。用短链接管理 README 中的链接有以下几个优势。
徽章 URL 的简化
有时会在 README 开头排列 CI 状态徽章、覆盖率徽章、许可证徽章等,但每个徽章的图片 URL 和链接 URL 都很长,导致 Markdown 源码难以阅读。使用短链接可以让徽章的 Markdown 更简洁,README 的编辑也更方便。
文档站点的导航
有些开源项目在 GitHub 仓库之外还运营着独立的文档站点。从 README 链接到文档站点各页面时,使用短链接可以灵活应对链接变更。即使文档站点的 URL 结构发生变化,只需更新短链接的重定向目标,无需修改 README。
CI/CD 流水线中的通知链接
有在 CI/CD 流水线失败时向 Slack 或 Teams 发送通知的做法。将通知消息中的链接替换为短链接,可以提升通知的可读性。
实现模式
在 GitHub Actions 工作流中,在构建失败时发送 Slack 通知的步骤中加入短链接生成。具体来说,将失败的工作流运行 URL 发送到短链接 API,将返回的短链接包含在 Slack 消息中。
这种方法的优势不仅在于通知消息更紧凑,还在于点击数可以作为了解日志是否被打开的线索。如果通知的查看率较低,就可以作为改进通知目标或消息内容的依据。
部署通知的应用
部署完成通知中也可以使用短链接。将部署环境的 URL、变更内容的 PR 链接、回滚操作文档链接等多个 URL 用短链接整理后包含在通知消息中,紧急情况下也更容易找到所需信息。
开源项目中的应用案例
在 Issue 模板中嵌入短链接
Bug 报告或功能请求的 Issue 模板中有时会包含贡献指南和行为准则的链接。将这些链接替换为短链接,即使指南的 URL 发生变更也无需修改模板。
在发布说明中的应用
发布说明中有时会列出与变更内容相关的 Issue 和 PR 链接。使用短链接可以让发布说明更清爽,用户也更容易查看感兴趣的变更详情。
开发团队的运营规范
在开发团队中运营短链接时,建立以下规范可以确保顺畅运作:
- 统一短链接的命名规则 (例如 `repo-issue-123`、`repo-pr-456`)
- 临时链接 (如代码审查请求) 设置有效期
- 永久链接 (如文档、指南) 不设有效期
- 在 Notion 或 Wiki 中管理短链接清单,确保团队全员可访问
将这些规范写入 `CONTRIBUTING.md`,有助于新的贡献者了解运营流程。短链接虽然是一个小工具,但在一些场景中可以减少开发工作流的麻烦。