GitHub Social Preview：尺寸、设计与设置。

什么是 GitHub Social Preview？

Social Preview 是 GitHub 为仓库链接提供的预览图片。仓库链接被分享到支持 Open Graph 的网站或聊天工具时，它会给仓库名和描述补充一个视觉身份。仓库管理员可以在设置中上传这张图。

它并不等于 README 顶图，虽然你可以选择复用同一份视觉素材。它本质上属于仓库的分享元数据。

GitHub Social Preview 的尺寸与文件要求

GitHub 接受小于 1 MB 的 PNG、JPG 或 GIF。官方文档建议图片至少为 640×320，并把 1280×640 列为最佳显示尺寸。两者都是 2:1。

• 推荐制作尺寸：1280×640 像素。
• 宽高比：2:1。
• 最大文件：小于 1 MB。
• 支持格式：PNG、JPG 或 GIF。

产品要求可能变化，请始终以 GitHub 官方 Social Preview 文档为准。

从仓库证据开始设计

最快的做法，是把仓库名放左边，再在右边加一块通用装饰。但这样也最容易抹掉仓库本身的特点。

更好的封面从三个问题开始：

1. 承诺：这个项目让用户做什么？
2. 证据：仓库能诚实地展示什么来支持这个承诺？
3. 排除：哪些次要信息、界面碎片和无法证实的卖点不应该出现？

答案可能是一个工作界面、一个角色、一个 3D 物体、一张图表、一段波形，也可能是从项目真实机制中推导出的视觉系统。只知道它属于“游戏”“工具”或“程序库”还不够。

如何使用截图，而不是直接发布截图

截图可能是最强证据，但仍然不是合格封面。浏览器边框、被切断的标题、调试文字、无关面板、过小控件和空场景，在缩小之后往往更难看。

应该保留

• 能让产品被认出来的核心交互或结果；
• 项目自带的插画、角色、物体和有辨识度的配色关系；
• 足以解释动作的界面上下文。

应该删除或重构

• 浏览器栏、调试层、意外裁切和半条 UI；
• 封面已经有标题时，截图中重复出现的标题；
• 遮住真实玩法或产品任务的大片空白；
• 没有语义作用的连线、面板与装饰线。

一套可靠的封面工作流

1. 查看仓库。阅读 README、关键代码、项目规则、截图、SVG 与主视觉素材。
2. 能运行时就运行。一个可用的本地 Web 界面通常比远端文件树提供更多信息。
3. 诊断素材。判断什么好看、什么有辨识度、什么冗余、什么缺失、什么容易误导。
4. 选择制作方式。排版与结构优先用可编辑 SVG；只有截图或插画仍是最清晰证据时才使用它。
5. 为缩略图构图。让仓库名、核心承诺和主要证据在 320×160 时仍然清楚。
6. 机械校验。确认 1280×640、小于 1 MB，并保留有效的可编辑源文件。
7. 检查明暗背景。链接卡片会出现在不同环境里。

如何在 GitHub 设置 Social Preview

1. 打开 GitHub 上的目标仓库。
2. 进入 Settings，你需要仓库管理员权限。
3. 找到 Social preview 区域。
4. 点击 Edit，上传 PNG、JPG 或 GIF。
5. 保存后打开公开仓库页，并重新检查链接预览。其他网站的缓存可能需要一段时间才会刷新。

GitHub 界面与要求可能变化，最后请以官方设置说明为准。

常见问题

文字在缩略图里读不清

很长的功能列表和小字说明，在 1280 像素时看似正常，缩小后会完全消失。最好只保留一个承诺和少量有证据的要点。

标题卡挡住了截图里最有用的部分

固定把标题放在左边，可能盖住导航、玩法或产品结果。先判断截图证明什么，再决定裁切和标题位置。

改变了项目原有的维度

3D 或 3D 加三渲二的项目，不应该因为 SVG 好画，就被压成一个扁平图标。维度本身就是身份的一部分。

加入没有意义的线

连线会暗示关系。它应该连接真实端点、表达真实流程、分隔真实区域，或被限制在图表范围内。否则就删掉。

把没有观察到的东西当成证据

只看静态文件，不能证明构建成功、游戏运行或场景正常。画面中的事实必须停留在实际查看过的证据范围内。

使用 RepoCover 生成 GitHub Social Preview

RepoCover 把上面的流程做成了一个 Codex Skill。它会输出可编辑的 SVG 和精确的 1280×640 PNG，检查原尺寸与缩略图，并把上传 GitHub 保留为另一次明确授权。

使用 $skill-installer，从 onovich/RepoCover 的 skill/repo-cover 安装 Skill。