如何在GitHub的README.md文件中添加图片？

Question

最近我加入了 GitHub，在那里托管了一些项目。

我需要在 README 文件中包含一些图片，但不知道该如何操作。

我搜索了一下，但得到的都是一些链接，告诉我“将图片托管在网络上，并在 README.md 文件中指定图片路径”。

是否有不依赖第三方网络托管服务的方法？

- Midhun MP

---

重复的问题，已于2012年在https://dev59.com/3mkw5IYBdhLWcg3wBl-A发布。 - leetNightshade

不离题，GitHub 是程序员的工具。 - Lance Roberts

可能是 如何在 GitHub 仓库的 README 中添加截图？ 的重复问题。 - Marcus

https://stackoverflow.com/a/77319849/4393351 - undefined

Answer 1

试试这个Markdown：

![alt text](http://url/to/img.png)

如果图片存储在您的代码库中，我认为您可以直接链接到其原始版本。例如：

![alt text](https://github.com/[username]/[reponame]/blob/[branch]/image.jpg?raw=true)

- Simon Lang

---

你应该考虑使用相对链接。 - mgalgs

相对链接在这里并不是很好的使用方式，想象一下你的自述文件也显示在 npm 上，它不能以这种方式托管图片 - 它需要链接到 GitHub。图片的 src 应该在 https://github.com 域名下，而不是 https://raw.github.com 子域名或 https://raw.githubusercontent.com 域名下。 - Lee Crossley

我最终选择了相对路径（因为我的文件都在根目录下，所以实际上是使用图片文件名称）。我之前一直在维护两份 README.md 文件，一份用于本地安装在 /usr/share/projectname/docs，另一份用于 Github。现在，由于图像文件名在两种情况下都能正常工作，我可以只使用同一个 README.md 文件。如果我想在其他地方发布我的 README 的某些部分，我需要将图像托管到其他地方或者放入 raw.github.com 的 URL 中。 - Colin Keenan

GitHub本身建议使用相对路径: https://help.github.com/articles/relative-links-in-readmes/ 绝对路径的一个主要缺点是，如果图像在主分支中被移动，仍然指向旧URL的其他分支将会断裂。 - Jack O'Connor

目前建议的域名似乎无法使用，链接应该是这样的：https://github.com/[用户名]/[仓库名]/blob/[分支名]/image.jpg?raw=true。请注意不要更改原意，保持语言通俗易懂。 - Slavik Shynkarenko

Answer 2

您也可以使用相对路径，例如

![Alt text](relative%20path/to/img.jpg?raw=true "Title")

也可以尝试以下操作，使用所需的.fileExtention：

![plot](./directory_1/directory_2/.../directory_n/plot.png)

- resultsway

---

是的。这绝对是最简单的方法，除非您担心性能问题。我要注意的是，这是相对于目录而不是仓库的，因此如果您在与'about_pics.md'相同的目录中有'myimage.png'，则标记是：！[这是什么](myimage.png)。 - Rich

这是一个很棒的解决方案，因为1）它能够正常运行，2）图像也能够显示在本地查看器中，不需要互联网访问。 - Régis B.

@Rich，您能详细说明一下有关性能方面的评论吗？使用相对路径方法会出现哪些性能问题？ - Lea Hayes

这个路径是相对于什么的？ - Dims

正如Lee Crossley所指出的那样，应该避免使用相对链接，因为当您的自述文件在npm上显示时它们会被破坏。相反，如果图像格式类似于SVG，则应该使用带有"?sanitize=true"标志的github.com域上的图像源进行链接。查看更多详细信息，请参阅此SO答案：https://dev59.com/AWYr5IYBdhLWcg3wRoSW#16462143 - AlienKevin

Answer 3

• 您可以创建一个新的问题
• 将图像上传（拖放）到其中
• 复制图像URL并将其粘贴到您的README.md文件中。

这里有一个详细的YouTube视频对此进行了详细说明：

https://www.youtube.com/watch?v=nvPOUdz5PL4

- Ahmad Ajmi

---

据我理解，您实际上并不需要“保存”问题。因此，在问题跟踪器中，您实际上不需要那些虚拟票证。问题是这种方法是否“安全”，也就是说，GitHub是否会在一段时间后检测到该图像为孤立状态，并因此从GitHub CDN中删除它？ - peterh

这个答案对我非常有效，不需要在仓库中保存新问题。我在YouTube上找到了一个详细解释的视频链接：https://www.youtube.com/watch?v=nvPOUdz5PL4。 - Francislainy Campos

这个答案可行，而且需要很少的努力。问题可以被丢弃，但图像的URL仍然存在。图像的URL格式为：https://user-images.githubusercontent.com/... - Sabuncu

这是一个很棒的技巧！但是有人知道 @peterh 提出的问题的答案吗？GitHub是否会定期清理那些孤立的图片（即没有与之相关联的问题）？ - Johnny Oshika

这实际上是最简单的方法，这让 GitHub 多少有些难堪。在折腾了 15 分钟的维基、gh-pages 和 github.io 后，我决定还是采用这个解决方案（再次）。 - joeytwiddle

Answer 4

这比那要简单得多。

只需将您的图像上传到存储库根目录，并链接到文件名，不需要任何路径，就像这样：

![Screenshot](screenshot.png)

- user3638471

---

不，我认为在git仓库中添加截图不是一个好的做法，特别是在根目录下。Ahmad Ajmi的回答更好。 - Arnaud P

不在根目录下，但你可以轻松地将其适应于“docs/images”或其他任何目录。在我看来，小的png截图也可以。 - Christophe Roussy

应该接受此解决方案，特别是考虑到Christophe建议将图片放在doc/目录下。 - Mike Ellis

完美..!! 如果PNG文件在另一个文件夹中。只需添加路径“folderName/screenshot.png”即可。 - Soumen

一个非常相似的答案，只需将此代码添加到您的 readme 文件中 <img src="screenshot.png"> （如果 screenshot.png 在您的根目录中）。 - garydavenport73

Answer 5

你还可以使用简单的HTML标签添加图片：

<p align="center">
  <img src="your_relative_path_here" width="350" title="hover text">
  <img src="your_relative_path_here_number_2_large_name" width="350" alt="accessibility text">
</p>

- Evin1_

---

当你在Markdown文件中使用HTML标签时，它将被通用文档转换器Pandoc忽略。 - XY Li

这是最好的方式，因为它可以居中或放置在一侧（对于较小的图像，至少如此）。 - Alexis Wilke

你如何指定相对路径？它不是相对于README.md（在所有情况下）吗？ - friederbluemle

这对我来说效果最好，包括使用VS Code编辑我的README.md文件并在GitHub上正确显示。 - risingPhoenix1979

这个很好用，简单而优雅。宽度太小了，谢谢。 - undefined

Answer 6

非常简单：可以使用 Ctrl + C/V 完成

大多数答案直接或间接地涉及将图片上传到其他地方，然后提供一个链接。

只需复制任何图像并在编辑 Readme.md 时粘贴即可轻松完成。

• 复制图像 - 您只需点击图像文件，使用Ctrl + C或使用截图工具复制截图图像到剪贴板。
• 然后，在编辑 Readme.md 时，只需执行 Ctrl + V

Github 将自动上传它到 user-images.githubusercontent.com 并插入一个指向它的链接

- Abdur Rahman

---

确实是最有用的答案。 即使我在寻找这个答案，但我得到的大部分答案都涉及将图像上传到某个地方，比如问题/存储库等，并提供其链接。这个真的很有帮助！ - user75648

这对其他人可能很明显，但请确保您在GitHub仓库的Web页面上编辑README文件。它在本地IDE中不起作用，您必须手动编辑存储库中的README文件，然后拖放。感谢您的回答！ - gmdev

这是编辑自述文件的最佳方法：复制图片，粘贴并保存。 - udorb b

我可以确认这个操作成功了 - 在 Github 编辑器中，cmd+v 的粘贴非常干净，并上传了图片。 - The Dembinski

这是我认为最重要的答案。 - Bidisha Das

这是一个被低估的答案。 - chepaiytrath

Answer 7

您也可以像插入其他格式一样，在Markdown文件中插入动画SVG图像。
这可以是GIF图像的一个很好的替代品。

![image description](relative/path/in/repository/to/image.svg)
OR
<img src="relative/path/in/repository/to/image.svg" width="128"/>

示例（假设图像位于存储库中的assets目录中）：

![My animated logo](assets/my-logo.svg)

结果：

_{如需根据 GitHub 暗/亮主题使用不同的图像，请参见此帖子。}

- Mahozad

---

如何减小宽度时使用 ![image description](relative/path/in/repository/to/image.svg)？ - Daniel Sogbey

@DanielSogbey 我认为你应该使用HTML元素*<img>，并设置宽度*属性，例如<img src="relative/..." width="100px" />。 - Mahozad

@DanielSogbey，我能在img标签中使用外部URL吗？我的不起作用。 - Sunlight

@SunPodder 抱歉晚来了，外部链接应该完美地运作。 - Daniel Sogbey

@SunPodder，太棒了。 - Daniel Sogbey

Answer 8

许多发布的解决方案不完整或不符合我的口味。

• 像imgur这样的外部CDN会增加另一个工具到链中。 毫无意义。
• 在问题跟踪器中创建虚拟问题是一种hack方法。 它会创建混乱并使用户感到困惑。 将此解决方案迁移到分叉或GitHub之外很麻烦。
• 使用gh-pages分支会使URL变得脆弱。 在项目上还有其他人维护gh-page时，可能不知道某些外部内容依赖于这些图像的路径。 gh-pages分支在GitHub上具有特定的行为，这对于托管CDN图像没有必要。
• 在版本控制中跟踪资产是一件好事。 随着项目的发展和变化，这是一种更可持续的方式来管理和跟踪多个用户的更改。
• 如果图像适用于软件的特定修订版本，则最好链接到不可变的图像。 这样，如果稍后更新图像以反映对软件的更改，阅读该修订版本的任何人都将找到正确的图像。

我喜欢的解决方案是受这个gist启发的，即使用具有特定版本永久链接的资产分支。

git checkout --orphan assets
git reset --hard
cp /path/to/cat.png .
git add .
git commit -m 'Added cat picture'
git push -u origin assets
git rev-parse HEAD  # Print the SHA, which is optional, you'll see below.

构建一个指向此版本图像的“永久链接”，并将其包装在Markdown中。

手动查找提交 SHA 不方便，因此可以按 Y 快捷方式获取到特定提交中文件的永久链接，如此 help.github 页面所述。

要始终显示 assets 分支上的最新图像，请使用 blob URL：

https://github.com/github/{repository}/blob/assets/cat.png 

（来自同一GitHub帮助页面 文件视图显示分支上的最新版本）

- paulmelnikow

---

这是对已被接受的答案的很好补充。资产得到跟踪，图像未在主分支中，不会混乱。只需注意git reset --hard命令；确保更改已提交。 - dojuba

在您的计算机上使用时，可以将它指向文件所在的任何位置（〜/下载，/tmp等）。 - paulmelnikow

我发誓我记得有一个目录可以创建，但不会显示在Github上。在我找到它之前，这篇文章似乎是使用的下一个最好的东西。谢谢！ - Shadoninja

我不明白为什么创建新的资产分支有什么优势。为什么不将资产保留在同一分支中，并使用这些资产的文件呢？ - ArtuX

这样就少了杂乱的东西。 - paulmelnikow

有些人不希望将纯文档/资源与代码混合在一起。我个人的解决方案通常是，我会决定将自述文件和一些截图视为根目录定义目的的一部分，如果有多个或非常少量的图像或其他内容，则将它们全部放入一个目录中。该目录的作用类似于分支，可以将它们打包并自动维护版本化资产，以匹配自述文件、其他文档和应用程序本身。这是一个更简单的心理模型，并且更容易复制/分叉/打包/迁移/备份等操作。而且仍然具有简单的相对路径。 - Brian White

Answer 9

我需要在我的README文件中包含一些图片，但我不知道如何实现。

我创建了一个小向导，可以让你为GitHub存储库的readme创建和自定义简单的图库：请参见ReadmeGalleryCreatorForGitHub。

该向导利用了GitHub允许img标签出现在README.md中的事实。此外，该向导还利用了将图片拖放到问题区域中上传图片的常见技巧（如本主题中的某个答案所述）。

- Felix K.

---

喜爱这个工具！ - Dan

我也喜欢这个工具，这应该成为Git的默认功能！！ - Shridutt Kothari

这太棒了！ - Ari K

这太棒了！ - Andreea

Answer 10

将您的图像（image.png）提交到文件夹（myFolder）中，并在您的 README.md 文件中添加以下行： ![可选文本](../master/myFolder/image.png)

- Darush