项目指南

GitHub 仓库社交预览图:尺寸、设置与检查清单

仓库社交预览图是分享仓库链接时可能显示的图片。用它让人快速理解项目:一个简短名称、一句实际用途,以及一个容易识别的示例。它补充 README,而不是替代文档。

GitHubStart 内容团队 · 更新于

准备合适的图片文件

GitHub 当前支持小于 1 MB 的 PNG、JPG 或 GIF 文件,推荐至少 640 × 320 像素,最佳显示尺寸为 1280 × 640。可以从较大的 2:1 画布开始,再检查缩小后的可读性。

以一个假设的 CSV 校验工具为例,可以放项目名、“导入前检查 CSV 文件”,以及简单的输入到错误提示示例。不要把整屏终端日志挤进缩略图。重要文字与边缘留出距离,以应对不同分享场景的裁切。

上传后检查实际分享效果

打开仓库 Settings,找到 Social preview,通过 Edit 上传图片。然后把公开仓库链接分享到目标用户会看到的平台,并在那里检查结果。上传成功不等于每个平台都会立即替换缓存中的预览。

  • 确认图片属于正在分享的那个仓库。
  • 上传前检查格式、像素尺寸和文件大小。
  • 保持足够对比度;透明图片要分别检查浅色和深色背景。
  • 如果仍显示旧图,先确认仓库设置已保存,再排查目标平台的缓存。

让预览内容与项目保持一致

图片、README 和版本公告应使用一致的项目名称与用途。如果截图展示实验性功能,应明确标注,或改用稳定的工作流程。不要添加虚构的 Star 数量、客户标识或性能承诺。

当项目的核心用途变化时,重新检查预览图。它是沟通素材,不是排名、点击率或 GitHub Star 数量的保证。

常见问题

这和仓库所有者的头像一样吗?

不一样。头像代表账号,自定义仓库社交预览图则用于分享链接时展示某个具体项目。

预览图可以使用透明背景吗?

GitHub 支持 PNG 透明度。应检查不同背景下的对比度;无法确定目标平台效果时,实色背景是实用选择。

上传后为什么仍显示旧图片?

先确认新图片已经保存在正确的仓库中。分享平台可能缓存预览,其刷新行为与仓库设置是分开的。

参考资料