写 GitHub 项目的 README图片几乎是门面中的门面。我自己维护的几个仓库早期 README 里全是纯文本项目介绍干巴巴的别人点进来扫两眼就划走了。后来花了一个周末把架构图、效果截图、演示 GIF 都整理进去该居中的居中、该同排的同排整个主页一眼看过去专业了不少最直观的变化是收藏数上来了也更愿意有人顺着 README 里的图去点进项目。这篇就专门讲透一件事在 GitHub 的 readme 文件里图片怎么上传、怎么正确引用以及怎么把居中、同行这些排列方式一次性搞定。这篇文章适合所有需要维护 GitHub 仓库的开发者无论你是刚接触 GitHub 的新手还是写了几年项目但一直懒得打理 README 的老手都可以直接用里面总结好的模板。全文不涉及任何外部工具依赖也几乎不需要额外安装软件跟着操作就能把图片排版这件事彻底理顺。1. 先搞清楚图片上传的三种途径1.1 最省事的做法直接传进仓库目录把图片直接放到仓库里然后通过相对路径引用这是我认为最稳妥、也最适合绝大多数项目的方式。具体操作分两步第一步在仓库根目录下新建一个assets或docs/images文件夹把需要用的截图、logo、架构图都丢进去第二步在 README 里用相对路径写图片引用格式是相对路径。这种方式最大的好处是图片跟代码一起进版本管理仓库 clone 下来之后图片天然就在不会出现图床挂了、图片变裂图的情况。对开源项目来说这让 README 的长期可维护性高了很多毕竟外部图床说不定哪天就失效了而自己的仓库永远都在。我个人的习惯是给图片命名时统一用小写字母加连字符比如architecture-diagram.png、demo-screenshot-01.png。这么做不只是为了好看而是因为 GitHub 上的文件路径是区分大小写的如果你在本地命名是Demo.PNG在 README 里写img src./demo.png大概率就会裂图。下面第 4 节我会专门讲这个坑。1.2 进阶做法用 Issue 当图床有些场景下你不想让图片进入项目仓库比如 README 里想放的是一张临时截图或者图很大、不想让仓库体积膨胀这时候可以借道 GitHub Issues 的附件功能。方法很朴素随便在自己的某个仓库哪怕是空仓库里新建一个 Issue把图片拖进输入框上传完成后复制图片链接再把 Issue 删掉即可。用这个方式拿到的图片地址是user-images.githubusercontent.com开头的属于 GitHub 官方静态资源域名只要 GitHub 本身正常这张图就能正常加载速度也还不错。我经常在项目还没有最终定稿设计稿的时候先用这种方式放几张占位图等正式素材准备好了再换成仓库内图片。注意虽然 Issue 删除后图片链接通常仍然可以访问但这只是通常并不代表官方承诺永久有效。正经项目我还是建议把最终需要的图片都挪进仓库这样最保险。1.3 外部图床不是不能用但要留个心眼有的教程会推荐用各种第三方图床来提升访问速度这个思路本身没问题但我踩过几次坑之后现在持保留态度。第三方图床如果哪天停止服务、或者改了防盗链规则你 README 里所有的图会在同一时间全部裂掉而且你往往是最后一个知道的人——毕竟平时不太会有人提醒你 README 的图挂了。如果你是做开源项目的我强烈建议优先用前两种方式。如果非要用外部图床至少保证项目里的核心图logo、架构图有仓库内的副本外部图只用来放那些丢了也不心疼的配图。2. Markdown 图片语法与路径选择2.1 基础语法必须记牢README 渲染使用的是 GitHub Flavored Markdown图片的基础语法和标准 Markdown 没有区别那个方括号里的替代文本看起来不起眼但它有两个实际作用一是当图片加载失败时页面上会显示这段文字读代码的人能大概知道这里本来想放什么二是很多辅助阅读工具比如屏幕阅读器会用它来朗读图片内容。我见过不少 README 的替代文本随手写了image、1这种无意义内容其实花五秒钟写清楚是性价比很高的事。2.2 相对路径 vs 绝对 URL 的取舍在 README 里引用图片路径有两种写法效果上有细微区别。第一种是相对路径比如前面提到的./assets/architecture.png。这种写法在仓库主页上能正确渲染因为 GitHub 会根据当前分支和路径自动拼出完整图片地址。它的好处是仓库换个域名托管、或者 fork 出去图片依然能跟仓库走不会因为域名变化而失效。第二种是绝对 URL即手动拼出完整的图片地址常见格式是https://raw.githubusercontent.com/用户名/仓库名/分支名/路径/图片.png这种写法的好处是不受 README 所在目录影响哪怕你把这段 Markdown 复制到别的仓库里图片依然能显示。缺点是地址里写死了分支名如果你默认分支从master改成了main或者将来重组了目录结构所有绝对 URL 都需要手动更新一遍。我在实际项目中两条路都用仓库内图片用相对路径确保 fork 友好只有那些需要跨仓库复用的图才用绝对 URL。2.3 分支、大小写这些容易翻船的细节关于路径有三个细节非常容易被忽略但任何一个都可能让图片裂掉。第一相对路径是相对于 README 文件所在位置的。如果 README 在仓库根部那么./assets/x.png就是指根目录下assets文件夹里的图但如果你的 README 放在docs子目录里那么引用assets里的图时就得写成../assets/x.png。这个道理和 HTML 里相对路径完全一致。第二文件路径的层级关系要写对。很多人习惯把图片放在image、img、images、assets、screenshots等不同名字的目录里这没问题但 README 里的路径必须和实际目录完全一致一个字母都不能差。第三GitHub 文件系统区分大小写。Demo.png和demo.png是两个不同的文件就算本地 Windows、macOS 系统不区分大小写推上 GitHub 之后一旦写错图片照样会裂。建议图片文件在第一时间就用小写加连字符命名彻底避开这个坑。3. 图片排列实操居中、同行、图文混排3.1 让图片居中三种写法任你选GitHub 的 README 渲染虽然对 Markdown 支持不错但标准 Markdown 语法里并没有居中这个选项。图片默认是靠左对齐的想实现居中必须借助 HTML 标签。我实测可用的方式有三种按推荐排序如下。最推荐的方式是包裹一层p aligncenterp aligncenter img src./assets/architecture.png alt项目架构图 /p如果想在一个区域里同时居中多张图片用div aligncenter更合适div aligncenter img src./assets/logo.png altlogo width120 img src./assets/badge.svg altbadge /div还有一部分项目会用到center标签这个标签属于 HTML 旧标准但实测在 GitHub 上依然能生效center img src./assets/architecture.png alt项目架构图 /center个人建议优先用p aligncenter或div aligncenter因为这两个是 HTML 标准标签语义也更明确。实际渲染时center也能用但既然有更稳妥的选择没必要冒兼容性的风险。3.2 让图片排在同一行两个核心思路同行这个问题问的人最多。标准 Markdown 里两张图即使写在相邻两行渲染出来也会变成上下排列想要真正并排显示就得靠下面两个思路。思路一把多张图片写在同一行 Markdown 里也就是图片语法之间只留空格、不换行  这个写法最简单GitHub 会把这些图片当作同一行里的多个行内元素渲染。缺点是你没法分别控制它们的大小如果三张图原始尺寸不一致排出来会参差不齐看起来不太整齐。思路二使用img标签配合宽度控制这是我在项目中用得最多的方式img src./assets/one.png width300 alt图1 img src./assets/two.png width300 alt图2 img src./assets/three.png width300 alt图3HTML 标签之间没有换行时就会自然排在同一行配合width属性把每张图设置成相同宽度就能得到非常整齐的等宽三图并排效果。这个思路本质上是在 GitHub 的 Markdown 渲染器里混写 HTMLGitHub 对此是明确支持的可以放心用。3.3 居中再加上同行组合拳怎么打很多项目想要的效果其实是多张图并排并且整体居中这时候就把前两节的方法组合起来。先用p aligncenter或div aligncenter包裹再在内部写同一行的img标签p aligncenter img src./assets/one.png width300 alt截图一 img src./assets/two.png width300 alt截图二 img src./assets/three.png width300 alt截图三 /p这样三张图既处于同一行又整体居中显示是 README 里展示三步操作演示图、三种功能对比图这类内容的标配写法。我自己的项目里凡是需要并排展示多张效果截图的地方基本都用这一个模板改一下路径和宽度就能直接复用。提醒一下width属性只对img标签生效Markdown 原生语法是不支持传宽度参数的。如果你用 GitHub 以外的某些平台比如一些文档系统它们可能支持这种写法但 GitHub 不支持所以统一用img最保险。3.4 更精致的排版表格布局、徽章、图文混排如果你觉得img单行排法不够灵活还可以利用 Markdown 表格来做更精细的布局。表格的每个单元格里都可以放图片通过控制列数和单元格内容能排出类似四宫格的效果| 左侧截图 | 右侧截图 | | -------- | -------- | |  |  |表格方式的好处是自带对齐和边框视觉上非常整齐适合展示新旧对比、界面左右分栏这类成对内容。缺点是在移动端阅读时表格可能出现横向滚动这需要你自己权衡。另外一个很常见的 README 元素是徽章badge就是项目名旁边那一排写着 build passing、license MIT 之类的小图标。徽章的引用方式和普通图片一样但由于它本身就很小通常不需要改宽度直接并排写就行p aligncenter img srchttps://img.shields.io/badge/build-passing-brightgreen altbuild img srchttps://img.shields.io/badge/license-MIT-blue altlicense /p这样做出来的徽章组居中且同行是开源项目 README 的经典门面。4. 常见问题与排查技巧实录4.1 图片裂了先按清单排查用了这么多年 GitHub我总结出一个裂图排查五步法按顺序走一遍百分之九十的问题都能定位到。第一步确认图片文件确实推送到远程仓库了。很多人本地能看到图是因为本地文件存在但git push之后才发现忘了git add图片目录。直接在浏览器里打开https://github.com/用户名/仓库名确认一下文件是否在。第二步核对路径大小写。这是绕不开的经典坑image和Image在 Linux 和 GitHub 上是不同路径把仓库里的实际文件路径复制出来再和 README 里写的逐字比对。第三步确认分支名。绝对 URL 里如果写死了master而仓库默认分支是main图片就会裂。推荐直接看仓库页面的地址栏那上面显示的分支名就是正确版本。第四步检查文件名里有没有空格或特殊字符。文件名中的空格在 URL 里需要编码成%20但只要你在仓库里用相对路径引用GitHub 一般会自动处理如果用绝对 URL空格非常容易出问题。最省事的办法是上传前就把文件名改成连字符风格。第五步清除缓存再刷新。有时候改动本身是对的但浏览器缓存了旧页面强制刷新CtrlF5或者开一个无痕窗口再看一眼。4.2 排版不生效多半是标签写法的问题常见的排版失效有两种情况。第一种是标签嵌套出问题比如把p aligncenter写成了p aligncenter但没闭合或者把div和p交叉嵌套GitHub 的渲染器对这类结构很敏感解析出来就是乱的。我的建议是每次只用一个包裹标签要么全程p要么全程div不要混用。第二种是图片之间换行导致同行失效。HTML 里如果两个img之间写了换行符在普通 HTML 中因为 inline 元素的特性通常不会有问题但在 GitHub 的 Markdown 渲染器里换行可能被解析成段落分隔导致图片从同一行变成上下两行。所以想要同行效果就必须严格保证img标签之间没有换行只可以留空格。还有一个细节是表格中图片的宽度控制。表格里的图片如果太大会把整个表格撑开影响阅读。建议在表格里也用img标签并设置width而不是直接写 Markdown 图片语法| 左边 | 右边 | | ---- | ---- | | img src./assets/left.png width280 | img src./assets/right.png width280 |4.3 几条实用的经验技巧最后把一些零散的实操心得集中整理出来当作速查手册用。第一图片大小是影响 README 加载体验的关键。一张几兆的 PNG 截图塞进 README访问者每次打开仓库都要等很久。建议截图类图片统一导成 JPG 或压缩后的 PNG单张控制在 300 KB 以内架构图、logo 这类图用矢量 SVG 更清晰。第二GIF 动图虽然能直观展示操作过程但尺寸往往很大。如果确实要用尽量裁剪掉多余画幅控制时长并且在 README 里放在靠后的位置不要让首屏被一个大 GIF 霸占。第三GitHub 对单个文件有 100 MB 的硬限制而且超过 50 MB 的文件会收到警告超过 100 MB 直接拒绝推送。对 README 配图来说无论如何都不应该接近这个量级。第四如果你在 README 里引用了其他仓库的图片文件建议先确认对方是否允许外链有些仓库会通过防盗链设置让外部引用失效。尽量使用自己仓库内的图片最可控。第五提交信息里写清楚add readme images这种描述或者把图片和 README 改动放在同一次提交里。这样以后回溯历史版本时能清楚地知道某张图和对应的文档是一起变更的排查问题会省很多时间。我在实际维护项目的过程中最深的体会是 README 的图片排版不需要花哨稳定和统一才是第一位。一套模板用到底所有并排图都统一宽度所有居中图都用同一个包裹标签整个项目的文档风格自然就立起来了。后面再做新项目、写新文档时直接复制自己常用的那套 HTML 模板几分钟就能把 README 的配图排版做完而且几乎不会出问题。