Markdown: Markdown 图片语法与 Alt 文本
一张好图胜过千言万语——在 Markdown 中插入图片只需要一行语法，但用好它有一些门道。
1. 你将学到
- Markdown 图片的基本语法
- 图片 Alt 文本的重要性和写法
- 图片加链接（点击图片跳转）
- 引用图片的集中管理方式
- 图片最佳实践（大小、格式、CDN）
2. 一个技术博客作者的真实故事
(1) 痛点：无法加载的图片
James 运营一个技术博客，每篇文章都会配几张截图。刚开始他把图片放在自己的服务器上，后来发现图片链接经常失效——服务器迁移了几次，旧链接全断了。更糟的是，他的图片文件名是中文的，在某些浏览器中无法加载。读者抱怨"图挂了"，文章的跳出率飙升到 70%。
(2) 解法：使用图床和规范命名
James 把所有图片迁移到 CDN 图床（如 Cloudinary），使用英文文件名，并为每张图片写好 Alt 文本。他还在 Markdown 中用引用图片的方式集中管理所有图片 URL。之后图片加载速度提升 3 倍，文章跳出率降到 35%。
3. 图片基础语法
(1) 行内图片
图片语法和链接非常相似，只是在前面加了一个 !：
MARKDOWN
| 部分 | 说明 | 示例 |
|---|---|---|
![Alt 文本] |
图片无法加载时显示的文字 | ![网页截图] |
(图片URL) |
图片文件地址 | (https://example.com/img/logo.png) |
(2) 图片尺寸调整
标准 Markdown 不支持设置图片宽高。需要时用 HTML 的 <img> 标签：
MARKDOWN
<img src="logo.png" width="200" alt="设置宽度为 200px">
💡 提示： 90% 的场景标准 Markdown 图片语法就够用了。确实需要控制大小时再使用 HTML
<img> 标签。
▶ 示例：插入一张本地图片
MARKDOWN
💡 提示： 好的 Alt 文本应该描述图片的内容和功能。对于装饰性图片（如分隔图标），Alt 文本可以为空
![] 但不要省略。
5. 图片加链接
(1) 点击图片跳转
将图片包裹在链接语法内，实现点击图片跳转：
MARKDOWN
[](fullsize-image.jpg)
[](https://example.com)
结构解析：
MARKDOWN
[ ← 链接开始
 ← 图片（点击区域）
] ← 链接结束
(https://example.com) ← 跳转目标
▶ 示例：图片链接的实际应用
MARKDOWN
## 项目徽章
[](https://github.com/user/repo/actions)
[](https://www.npmjs.com/package/package-name)
## 产品截图
| 功能 | 截图 |
|:-----|:-----|
| 仪表盘 | [](img/dashboard-full.png) |
| 设置页 | [](img/settings-full.png) |
💡 提示： 这是 GitHub README 中常见的"徽章（Badge）"用法。点击徽章跳转到对应服务（如 CI 状态页、npm 包页面）。
6. 引用图片
与引用链接类似，图片 URL 也可以集中管理：
MARKDOWN
正文中：
![公司 Logo][logo]
![产品截图][screenshot1]
文档末尾定义：
[logo]: https://cdn.example.com/logo.png "公司 Logo"
[screenshot1]: https://cdn.example.com/screenshots/v2/dashboard.png "新版仪表盘截图"
💡 提示： 引用图片特别适合维护大量图片的文档集。当迁移到新的图床时，只需要改文件末尾的 URL 定义。
7. 图片最佳实践
(1) 文件格式选择
| 格式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| PNG | 截图、图标、透明背景 | 无损、质量高 | 文件大 |
| JPEG | 照片、复杂色彩图 | 文件小 | 有损压缩 |
| SVG | 图标、Logo、插图 | 无限缩放、文件极小 | 不适合照片 |
| GIF | 简单动画 | 兼容性好 | 色彩少、文件大 |
| WebP | 替代 PNG/JPEG | 体积小 25-35% | 部分旧浏览器不支持 |
(2) 图片优化建议
MARKDOWN
1. 控制大小：单张图片不超过 500KB，推荐 100-300KB
2. 使用 CDN：加速全球加载
3. 英文文件名：logo.png ✅ logo-公司.png ❌
4. 合理目录：assets/images/ 或 img/
5. 写 Alt 文本：每张图片必须写描述性 Alt 文本
⚠️ 注意： 在 GitHub README 中直接引用本地图片路径（
./assets/image.png）是安全的，但引用外部图床需要确保该服务稳定可靠。
▶ 示例：产品说明文档中的图片
MARKDOWN
## UI 界面展示
### 登录页面
### 仪表盘
> **注：** 点击图片可查看高清大图
[](img/dashboard-full.png)
8. 完整示例：项目 README 中的图片展示
TEXT
📖 仅展示
Awesome App 项目 README 结构：
标题行：# Awesome App + 徽章图片
截图表格：移动端 | 桌面端
安装命令：npm install awesome-app
Logo 引用：[logo]: https://cdn.example.com/logo.png
预期效果：图文并茂的 GitHub README，包含项目横幅、徽章、截图展示，Logo 集中管理在文档末尾。
❓ 常见问题
Q 图片太大了，在 Markdown 中怎么缩小？
A 标准 Markdown 不支持尺寸控制。用 HTML：
<img src="url" width="400" alt="描述">。Q GitHub 上图片路径怎么写？
A 用相对路径
./assets/image.png 引用仓库内的图片。也可以用绝对 URL 引用外部图床。Q GIF 动图能用吗？
A 能。语法与静态图片完全相同。但注意文件大小——一个大 GIF 可能 5-10MB，影响页面加载速度。
Q 图片 Alt 文本最长多少？
A 没有硬性限制，但推荐 125 字以内。屏幕阅读器通常会截断过长 Alt 文本。
Q SVG 图标怎么用？
A Markdown 直接引用
.svg 文件即可。也可以在 Markdown 中嵌入 SVG 源代码（部分解析器支持）。📖 小节
- 图片语法
与链接语法仅差一个! - Alt 文本对无障碍和 SEO 至关重要，要描述图片内容和功能
- 图片加链接：
[](链接)实现点击跳转 - 引用图片集中管理 URL，便于维护和迁移
- 推荐使用 CDN 图床、英文文件名、控制文件大小
- 需控制图片大小时，回退到 HTML 的
<img>标签
📝 作业
-
基础题：在 Markdown 中插入一张图片（可以是网络图片或本地图片），写好描述性 Alt 文本。然后在浏览器中禁用图片加载，验证 Alt 文本是否正常显示。
-
进阶题：创建一个小项目，在 README.md 中实现"点击缩略图查看大图"功能——页面显示小图，点击后在新标签页打开原图。
-
挑战题：用引用图片方式维护一份"网站截图集"文档，包含至少 5 张截图，URL 集中定义在文档末尾。然后尝试将这些截图改为 WebP 格式，比较文件体积变化。
