跳过主要内容

GitHub README 与 PR 动图压缩

让你的开源项目 README、Issue 和 Pull Request 演示动图既清晰又秒开。稳妥满足 GitHub 10MB 附件上限与 1MB 社交预览图限制,同时避免污染 Git 仓库历史。

更新日期:

拖入 GIF 或选择文件

粘贴 HTTPS 图片地址

按平台准备 GIF

平台限制可能变更。压缩目标不是平台上限,请核对实际输出及当前上传入口的要求。

GitHub

GitHub 对 Issue/PR 拖拽附件与仓库社交预览图分别设定了不同上限。

  • 在 Issue、Pull Request 和评论中上传的图片与 GIF 单文件上限为 10MB。
  • 仓库社交预览图(PNG、JPG 或 GIF)须小于 1MB,推荐尺寸 1280×640 像素。
  • 不要把大体积 GIF 直接提交进 Git 仓库历史;建议压缩至 1–2MB 后通过 Issue/PR 拖拽托管链接嵌入 README。

核验日期:

操作步骤

  1. 拖入终端或 UI 操作录屏 GIF,默认选中 2MB 清晰度均衡预设。
  2. 本地完成压缩后,放大检查代码字体与按钮文字是否依然锐利。
  3. 若字迹发虚,先裁剪多余桌面背景,而不是把整张图缩小。
  4. 下载后拖进 GitHub Issue/PR 输入框生成托管链接,或接入 API/MCP 自动化处理。

GitHub 各入口的 GIF 大小限制一览

GitHub 官方规定 Issue、PR 与评论区上传的图片与 GIF 不得超过 10MB;仓库设置中的 Social Preview 社交分享卡片须小于 1MB(推荐 1280×640 像素)。

1 — Issue 与 PR 附件上限 10MB,README 推荐 1 到 2MB · 2 — 仓库社交预览图 1280×640 且小于 1MB
1 — Issue/PR 拖拽附件(上限 10MB,README 建议 1–2MB) · 2 — 仓库社交预览图(1280×640px,<1MB)
GitHub 位置官方上限工程最佳实践
Issue / PR / 评论附件图片与 GIF 上限 10MB压至 1–3MB,方便协作者快速打开 Review。
README.md 演示动图通过 PR/Issue 托管同享 10MB避免直接 commit 进仓库,优先裁剪有效窗口。
仓库 Social Preview小于 1MB(1280×640px)用静态图或极简 <1MB 动图。

实测案例

这些自制案例使用与本工具相同的压缩引擎处理。结果取决于源文件,不代表你的文件会获得相同效果。

实测数据 (JSON)
目标原文件实际大小
目标: 1000 KB1,141,589 字节数903,284 字节数已达到目标
裁剪并截短的教程 · 目标: 1000 KB560,904 字节数531,027 字节数已达到目标

目标: 1000 KB

原文件 · 1,141,589 字节数

目标: 1000 KB: 原文件

输出 · 903,284 字节数

目标: 1000 KB: 输出

尺寸: 640 × 360px
帧数: 40 · 时长: 4 秒

实际应用的设置: 256 最多颜色数 · 有损等级 20

查看局部细节

原文件

目标: 1000 KB: 原文件

输出

目标: 1000 KB: 输出

裁剪并截短的教程 · 目标: 1000 KB

编辑后的源文件 · 560,904 字节数

裁剪并截短的教程 · 目标: 1000 KB: 编辑后的源文件

输出 · 531,027 字节数

裁剪并截短的教程 · 目标: 1000 KB: 输出

尺寸: 420 × 182px
帧数: 20 · 时长: 2 秒

实际应用的设置: 256 最多颜色数 · 有损等级 0

编辑后的源文件: 640 × 360px · 40 帧数 · 4 秒 → 420 × 182px · 20 帧数 · 2 秒

查看局部细节

原文件

裁剪并截短的教程 · 目标: 1000 KB: 原文件

输出

裁剪并截短的教程 · 目标: 1000 KB: 输出

为什么不建议把大 GIF 直接 commit 进 Git 仓库?

每次把 8MB 的未压缩 GIF 提交或覆盖到仓库中,Git 都会把历史二进制永久保留在对象库里,导致后续所有开发者的 `git clone` 和 CI 拉取变慢。

更干净的做法是先把录屏压到 1–2MB,拖入任意 Issue 或草稿 PR 评论区自动上传到 GitHub 静态附件域名,再把生成的 Markdown 链接贴进 README.md。

  1. 裁剪录屏,只保留编辑器或终端窗口
  2. 用截短工具删掉开头结尾的空闲停顿
  3. 压至 1–2MB 并确认等宽代码字体清晰
  4. 通过 GitHub 拖拽托管,或在 CI 中调用 REST API 自动压缩

怎么在 2MB 内保持终端代码文字清晰不糊?

终端和 IDE 界面大部分背景静止不变,非常适合 GIF 压缩。真正毁掉 12px 代码字体的往往是整图缩放——先把 1440px 全屏裁剪为 720px 核心窗口,像素面积减少 75%,文字却保持原像素 1:1 锐利。

常见问题

GitHub Issue 和 PR 最大能上传多大的 GIF?

GitHub 官方限制 Issue、Pull Request 和评论中上传的图片与 GIF 单文件最大 10MB。

为什么我的 README 外链 GIF 加载失败或超时?

GitHub 的 Camo 图片代理对超大外链图片容易超时。把动图压缩到 2–5MB 以内能大幅提升全球加载成功率。

可以在 GitHub Actions 里自动压缩演示 GIF 吗?

可以。CompressGIF 提供免费额度 REST API(每月 500 积分,无需绑卡)和 MCP 服务,适合集成进文档构建流水线。

README 里用 MP4 视频还是 GIF 更好?

GitHub 已支持在 README 和 PR 中拖拽上传 MP4(免费账号 10MB,付费 100MB)。需要自动循环无播放条用 GIF,长录屏建议转 MP4。