Markdown 图片基础语法：从零开始掌握图文并茂的写作
在写技术文档、开发笔记或博客时，纯文字容易显得枯燥，尤其当你想展示代码运行效果、界面截图或架构图时，一张清晰的图片往往胜过千言万语。而 Markdown 图片，正是让文本“活”起来的关键工具之一。它不仅语法简洁，而且兼容性极强，几乎所有的代码托管平台（如 GitHub、GitLab）、静态网站生成器（如 Hexo、VuePress）都原生支持。
想象一下：你正在写一篇关于 Vue 3.0 响应式原理的文章，用一段代码描述 ref 的使用，但光靠文字描述“数据变化会自动更新视图”可能不够直观。此时插入一张模拟界面变化的动图或静态图，读者瞬间就能理解核心逻辑。这就是 Markdown 图片的魅力——让信息传递更高效、更直观。
那么，如何正确使用 Markdown 图片？别急，接下来我们将从基础语法到高级技巧，一步步带你掌握这项实用技能。
图片语法详解：三种写法全解析
Markdown 图片的核心语法非常简单，由三部分构成：。其中：
!表示这是一个图片引用；[]中填写图片的替代文字（alt text），当图片无法加载时会显示这部分内容；()中填写图片的路径或 URL。
我们来看一个最基础的例子：
这段代码表示：插入一张名为 vue3-reactivity.png 的图片，其替代文字为“Vue 3.0 响应式原理图”。如果图片加载失败，浏览器会显示“Vue 3.0 响应式原理图”这段文字。
⚠️ 注意：替代文字不是可有可无的装饰，它对无障碍访问（如屏幕阅读器）至关重要，也影响搜索引擎对页面内容的理解。
除了相对路径，你还可以使用绝对路径或网络 URL。比如：
这将直接从 GitHub 的 CDN 加载图标。不过要注意：外链图片存在失效风险，建议本地化存储重要图片。
图片路径的三种形式对比
| 形式 | 示例 | 适用场景 | 说明 |
|---|---|---|---|
| 相对路径 | ./images/photo.png |
本地项目中 | 适合文件组织清晰的项目，路径从当前文档出发 |
| 绝对路径 | /static/images/logo.png |
网站根目录 | 适用于静态站点生成器，路径以根目录为起点 |
| 网络 URL | https://example.com/img.jpg |
外部资源 | 快速引用网络图片，但依赖网络稳定性 |
相对路径最常用，尤其在本地写作或 Git 仓库中。建议将所有图片统一放在 images/ 文件夹下，保持项目整洁。
图片尺寸与对齐：让排版更美观
仅仅插入图片还不够，如何控制它的显示效果？比如你希望图片宽度占满容器，或者让图片居中对齐？这就涉及 Markdown 图片的样式控制。
虽然 Markdown 本身不支持直接设置宽高或对齐方式，但你可以通过 HTML 标签嵌入来实现。这是 Markdown 的一个强大特性：允许内联 HTML。
例如，你想让图片居中显示，可以这样写：
<div style="text-align: center;">
</div>
✅ 说明：
<div>标签包裹图片，通过style="text-align: center;"实现水平居中。注意，这里图片本身仍是 Markdown 语法，HTML 只负责布局。
如果想设置图片宽度，比如让图片宽度为 80%，可以这样：
<img src="./images/chart.png" alt="数据统计图" style="width: 80%; height: auto;">
✅ 说明：
<img>是 HTML 的图片标签，src指定图片路径，alt是替代文字，style设置宽度为 80%，height: auto保持比例不变。
你也可以结合 CSS 类来实现更复杂的样式控制。例如，在项目中定义一个 .centered-image 类：
.centered-image {
display: block;
margin: 0 auto;
max-width: 100%;
height: auto;
border-radius: 8px;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.1);
}
然后在 Markdown 中引用：
<img src="./images/diagram.png" alt="系统架构图" class="centered-image">
这样，所有使用该类的图片都会自动居中、带圆角和阴影，提升整体视觉体验。
图片与文字混排：构建流畅的阅读体验
在实际写作中，你很少只插入一张孤立的图片。更多时候，图片需要与文字配合，形成“图文并茂”的表达方式。比如描述一个功能流程时，用图展示步骤，用文字解释关键点。
这时，你可以使用 Markdown 的段落结构，把图片嵌入到文本中间。例如：
在配置 Vue 3.0 的
setup函数时，我们通常使用ref来声明响应式变量。
如图所示，
ref返回一个对象，包含一个value属性，用于读取和修改值。当值变化时，视图会自动更新。
这种写法非常自然：文字描述问题，图片展示实例，读者能快速建立“文字 → 图像 → 理解”的认知链条。
💡 小技巧：如果你发现图片与文字之间间距过大，可以在图片前后加空行，或使用 HTML 的
style="margin: 0;"来压缩间距。
<img src="./images/button-click.png" alt="按钮点击事件" style="margin: 0;">
图片命名与组织：提升项目可维护性
你有没有遇到过这样的问题：写了一堆文章，图片文件名却叫 1.png、pic2.jpg，时间一长完全记不清哪张是哪张？这不仅影响效率，还容易出错。
良好的图片命名规范是专业写作的体现。建议遵循以下原则：
- 使用小写字母，用连字符
-分隔单词，避免空格； - 用描述性名称，如
user-login-form.png而不是login.png； - 添加版本或用途前缀，如
v1-、diagram-、error-等。
例如：
api-request-flow.png：展示 API 请求流程；error-404-page.png：404 页面截图；vue3-setup-composition.png：Vue 3 组合式 API 示例。
同时，建议将图片统一存放在 images/ 文件夹下，并按主题分目录，如：
docs/
├── images/
│ ├── vue3/
│ │ ├── reactivity.png
│ │ └── setup.png
│ ├── java/
│ │ └── thread-pool.png
│ └── diagrams/
│ └── architecture.png
└── guide.md
这样，当你需要查找某张图时，只需按目录层级快速定位，极大提升写作效率。
图片工具推荐：从截图到压缩
在实际操作中，你可能需要从网页、界面或代码运行结果中提取图片。以下是一些实用工具推荐：
- 截图工具：Windows 自带的“截图工具”、macOS 的
Shift + Command + 4、Snipaste（跨平台，支持标记）； - 在线工具：https://www.remove.bg 可一键去除图片背景；
- 图片压缩：使用 TinyPNG 或 Squoosh 压缩图片大小，避免文档体积过大；
- 矢量图生成：使用 Mermaid Live Editor 将流程图、时序图以代码形式生成 SVG，再嵌入文档。
✅ 重要建议：发布前务必检查图片加载是否正常。在本地预览时，打开浏览器开发者工具（F12），查看“Network”标签页，确认所有图片请求状态为 200。
结语：让每一张图都讲清楚一个故事
掌握 Markdown 图片，不只是学会写一行代码，更是学会如何用视觉语言表达思想。一张图，可以是一个操作步骤的指引，一个架构设计的缩影，一段代码运行的快照。
当你在写技术文档时，不妨问自己：这一段文字，是否需要一张图来辅助理解？是否可以通过图片让读者“一眼看懂”？答案往往是肯定的。
从今天起，让每一篇文档都拥有清晰的视觉语言。用 Markdown 图片，把抽象概念变得具体，把复杂逻辑变得简单。你会发现，写作不仅在传递知识，更在构建连接——连接代码与人，连接思想与视觉。
记住：好的技术写作，是文字与图像的协奏曲。而你，正是这场演出的指挥者。