Markdown 添加本地图片完整指南

在使用 Markdown 编写文档时，插入本地图片是一个常见需求。本文将详细介绍如何在 Markdown 中正确引用本地图片，并提供实用技巧和常见问题解答。

基本语法

Markdown 插入图片的标准语法如下：

![替代文本](图片相对路径)

例如：

![示例图片](images/example.jpg)

路径说明

• 相对路径：推荐使用相对路径，确保文档可移植。例如：./images/photo.png 或 ../assets/logo.jpg。
• 绝对路径：不推荐，因为不同设备路径结构不同，会导致图片无法显示。

目录结构建议

为便于管理，建议将图片统一放在一个文件夹中，例如：

project/
├── README.md
└── images/
    ├── cover.png
    └── diagram.jpg

此时在 README.md 中引用图片应写作：

![封面图](images/cover.png)

常见问题与解决方法

1. 图片不显示？ 检查路径是否正确，注意大小写敏感（尤其在 Linux/macOS 系统）。
2. 在 GitHub 上显示正常，本地预览失败？ 可能是本地 Markdown 预览工具对路径支持不同，建议使用 VS Code 或 Typora 等主流编辑器。
3. 能否调整图片大小？ 标准 Markdown 不支持，但部分平台（如 Typora、Obsidian）支持 HTML 语法：
   <img src="images/photo.jpg" width="300" />

小贴士

• 始终为图片提供有意义的“替代文本”（alt text），提升可访问性。
• 避免使用中文或特殊字符命名图片文件，防止路径解析错误。
• 若用于网页发布（如 Jekyll、Hugo），请参考对应静态站点生成器的资源路径规则。