垦荒学园

简体中文

English

简体中文

English

切换主题

Markdown 图片 ​

在文档中添加图片可以让内容更加生动和易于理解。Markdown 提供了简单的图片插入语法，支持本地图片、网络图片等多种方式。本章将详细介绍 Markdown 图片的各种用法。

基本图片语法 ​

语法格式 ​

markdown
![替代文本](图片URL)
![替代文本](图片URL "可选标题")

示例 ​

markdown
![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

![带标题的图片](https://example.com/image.jpg "这是图片标题")

效果：

GitHub Logo

带标题的图片

图片语法说明 ​

替代文本（Alt Text） ​

替代文本在图片无法加载时显示，对 SEO 和无障碍访问很重要：

markdown
❌ ![图片](image.jpg) - 缺少描述
✅ ![一只可爱的猫咪](cat.jpg) - 有意义的描述
✅ ![架构图](architecture.png) - 描述图片内容

图片标题 ​

鼠标悬停在图片上时显示：

markdown
![产品截图](screenshot.jpg "点击查看大图")

引用式图片 ​

语法 ​

markdown
![替代文本][图片引用]

[图片引用]: 图片URL "可选标题"

示例 ​

markdown
这里有两张图片：

![Logo][logo]
![图标][icon]

[logo]: https://github.com/github.png
[icon]: https://example.com/icon.png

效果：

这里有两张图片：

Logo图标

引用式图片的优势 ​

  • 集中管理：图片 URL 统一定义
  • 易于维护：修改 URL 只需改一处
  • 可复用：同一图片多次使用
  • 文档清晰：内容不会被 URL 打断

本地图片 ​

相对路径 ​

markdown
![本地图片](./images/photo.jpg)
![子目录图片](./assets/icons/logo.png)
![上级目录图片](../photos/album.jpg)

绝对路径 ​

markdown
![绝对路径](/home/user/project/images/pic.jpg)

网络图片 ​

直接链接 ​

markdown
![网络图片](https://example.com/image.jpg)
![GitHub 图标](https://github.com/github.png)

稳定的 CDN ​

markdown
![CDN 图片](https://cdn.example.com/images/photo.jpg)

图片链接 ​

将图片作为链接 ​

markdown
[![图片描述](图片URL)](链接URL)

示例 ​

markdown
[![访问 GitHub](https://github.com/github.png)](https://github.com)

[![点击查看大图](./thumbnail.jpg)](./large.jpg)

效果：

访问 GitHub

HTML 图片标签 ​

更灵活的控制 ​

html
<img src="image.jpg" alt="描述" width="300" height="200">

带样式的图片 ​

html
<img src="image.jpg" alt="描述" style="border-radius: 10px; box-shadow: 0 2px 5px rgba(0,0,0,0.3);">

响应式图片 ​

html
<img src="image.jpg" alt="描述" style="max-width: 100%; height: auto;">

图片尺寸控制 ​

Markdown 语法限制 ​

标准 Markdown 不直接支持尺寸调整，需要使用 HTML：

html
<!-- 固定尺寸 -->
<img src="image.jpg" width="500" height="300">

<!-- 宽度自适应 -->
<img src="image.jpg" width="50%">

<!-- 最大宽度 -->
<img src="image.jpg" style="max-width: 800px; width: 100%;">

GitHub Flavored Markdown ​

GitHub 支持使用 | 分隔符：

markdown
![图片](image.jpg|300)

图片对齐 ​

HTML 方式 ​

html
<!-- 左对齐 -->
<img src="image.jpg" align="left">

<!-- 右对齐 -->
<img src="image.jpg" align="right">

<!-- 居中 -->
<center>
    <img src="image.jpg">
</center>

使用 div 容器 ​

html
<div style="text-align: center;">
    <img src="image.jpg" alt="居中图片">
    <p>图片说明</p>
</div>

图片说明 ​

基本说明 ​

markdown
![图片](image.jpg)

*图片 1：这是一个示例图片*

带编号的说明 ​

markdown
![架构图](architecture.png)

**图 1**：系统架构示意图

并排图片的说明 ​

markdown
| 图1：组件A | 图2：组件B |
|----------|----------|
| ![图A](a.jpg) | ![图B](b.jpg) |

图片优化建议 ​

1. 选择合适的格式 ​

格式适用场景
JPG照片、复杂图像
PNG图标、透明背景
SVG图标、矢量图形
WebP现代浏览器、优化压缩
GIF简单动画

2. 压缩图片 ​

使用工具压缩图片大小：

  • TinyPNG
  • ImageOptim
  • Squoosh

3. 使用适当尺寸 ​

markdown
✅ ![缩略图](thumb-200x200.jpg)
✅ ![中等图片](medium-800x600.jpg)
❌ ![超大图片](huge-4000x3000.jpg)

4. 提供替代文本 ​

markdown
✅ ![产品截图](screenshot.jpg "产品功能展示")
❌ ![图片](image.jpg)

图片存储最佳实践 ​

目录结构 ​

project/
├── docs/
│   └── README.md
├── images/
│   ├── screenshots/
│   ├── diagrams/
│   └── icons/
└── assets/
    └── logos/

命名规范 ​

markdown
<!-- 推荐 -->
![系统架构图](./images/diagrams/architecture.png)
![用户界面截图](./images/screenshots/ui-2024.png)

<!-- 不推荐 -->
![图片1](./img1.jpg)
![screenshot](./123.png)

版本控制 ​

  • 大文件使用 Git LFS
  • 压缩图片后再提交
  • 考虑使用 CDN 或图床

图片托管方案 ​

1. 本地存储 ​

markdown
![本地图片](./images/photo.jpg)

优点： 完全控制、不依赖外部服务
缺点： 增加仓库大小、加载速度慢

2. 图床服务 ​

markdown
![图床图片](https://img.example.com/photo.jpg)

常用图床：

  • Imgur
  • Cloudinary
  • 七牛云
  • 阿里云 OSS
  • GitHub 仓库

3. CDN 加速 ​

markdown
![CDN 图片](https://cdn.example.com/image.jpg)

图片占位符 ​

使用占位符服务 ​

markdown
![占位符](https://via.placeholder.com/300x200?text=Placeholder+Image)

常用占位符服务：

  • Placehold.co
  • Placeholder.com
  • Dummyimage.com

自定义占位符 ​

markdown
![待添加图片](./images/coming-soon.png)

图片加载优化 ​

懒加载 ​

html
<img src="image.jpg" loading="lazy" alt="描述">

延迟加载 ​

markdown
默认显示缩略图，点击加载高清图：

[![缩略图](thumb.jpg)](large.jpg)

特殊图片类型 ​

SVG 图片 ​

markdown
![SVG 图标](./icons/logo.svg)

GIF 动图 ​

markdown
![动画演示](./animation.gif)

数据 URI 图片 ​

html
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="内嵌图片">

不同平台的图片支持 ​

GitHub ​

  • 支持本地和远程图片
  • 图片托管在仓库中
  • 自动生成缩略图

GitLab ​

  • 支持图片拖拽上传
  • 可以直接粘贴图片

Typora ​

  • 支持拖拽插入图片
  • 可以复制粘贴图片
  • 自动管理相对路径

VS Code ​

  • 需要使用预览插件
  • 支持相对路径链接
  • 图片悬停显示

图片安全 ​

防止盗链 ​

  • 使用引用式图片
  • 考虑添加水印
  • 使用可靠的图床

验证来源 ​

markdown
<!-- 来自可信来源 -->
![官方文档](https://docs.python.org/images/logo.png)

<!-- 未知来源谨慎使用 -->
![未知图片](https://random-site.com/image.jpg)

实战示例 ​

文章插图 ​

markdown
## 产品介绍

我们的产品具有以下特点：

![产品界面](./images/product-ui.jpg)

如上图所示，界面简洁直观，易于上手。

技术文档流程图 ​

markdown
## 工作流程

系统执行流程如下：

![流程图](./images/diagrams/workflow.png)

**图 1**：系统工作流程示意图

教程步骤图 ​

markdown
### 步骤 1：安装软件

![安装界面](./images/screenshots/install.png)

如上图，点击"下一步"继续安装。

### 步骤 2：配置设置

![配置界面](./images/screenshots/config.png)

完成配置后，点击"保存"。

图片画廊 ​

markdown
## 作品展示

| 作品 1 | 作品 2 | 作品 3 |
|--------|--------|--------|
| ![作品1](./gallery/work1.jpg) | ![作品2](./gallery/work2.jpg) | ![作品3](./gallery/work3.jpg) |

*图 1：精选作品展示*

常见问题 ​

Q: 图片无法显示？ ​

A: 检查以下几点：

  • URL 是否正确
  • 文件是否存在
  • 权限是否正确
  • 网络是否可访问

Q: 如何在 Markdown 中调整图片大小？ ​

A: 使用 HTML 标签：

html
<img src="image.jpg" width="500">

Q: 图片加载慢怎么办？ ​

A:

  • 压缩图片大小
  • 使用 CDN
  • 使用懒加载
  • 提供 WebP 格式

Q: 如何批量插入图片？ ​

A: 使用脚本或编辑器插件自动化处理。

小结 ​

本章详细介绍了 Markdown 中图片的使用方法：

  • 基本语法：![alt](url) 格式
  • 引用式图片：集中管理图片 URL
  • 本地和网络图片：多种图片来源
  • 尺寸和对齐：使用 HTML 控制
  • 优化建议：格式选择、压缩、命名
  • 最佳实践：合理的目录结构和命名

掌握图片的各种用法，可以让你的文档更加生动和专业。

下一步： 学习 Markdown 表格 的创建方法。