Markdown 图片使用指南

· BlogAI
#Markdown #Images #Tutorial

Markdown 图片使用指南

本文介绍如何在 Astro 博客中管理和使用图片。

图片存储结构

推荐的图片存储方式：

src/content/blog/
├── images/              # 所有博客图片统一存放
│   ├── earth.png
│   ├── example.jpg
│   └── diagram.svg
├── article-1.md
├── article-2.md
└── markdown-images-guide.md

方法一：相对路径引用（推荐）

在 Markdown 中使用相对路径引用图片：

![地球图片](./images/earth.png)

实际效果：

地球图片

优点

  • ✅ 简单直观
  • ✅ 图片和文章一起管理
  • ✅ 自动优化（Astro 会处理）
  • ✅ 支持版本控制

缺点

  • ❌ 图片会被打包到构建产物中
  • ❌ 大图片会增加构建时间

方法二：public 目录（静态资源）

将图片放在 public/ 目录：

public/
└── images/
    └── logo.png

在 Markdown 中引用：

![Logo](/images/logo.png)

优点

  • ✅ 不经过构建处理，直接复制
  • ✅ 适合大量静态图片
  • ✅ 可以被外部直接访问

缺点

  • ❌ 不会被优化
  • ❌ 路径必须以 / 开头

方法三：使用 Astro 的 Image 组件

在 .astro 文件中使用 Image 组件获得最佳性能：

---
import { Image } from 'astro:assets';
import myImage from '../content/blog/images/earth.png';
---

<Image src={myImage} alt="地球" width={800} height={600} />

优点

  • ✅ 自动优化（WebP、AVIF）
  • ✅ 响应式图片
  • ✅ 懒加载
  • ✅ 最佳性能

图片优化建议

1. 图片格式选择

  • 照片：JPEG/WebP
  • 图标/Logo：SVG/PNG
  • 截图：PNG
  • 动画：GIF/WebP

2. 图片大小

# 使用 ImageMagick 压缩
magick input.jpg -quality 85 output.jpg

# 使用 TinyPNG API
npx tinify input.png

3. 响应式图片

在 Markdown 中使用 HTML：

<picture>
  <source srcset="./images/earth.webp" type="image/webp">
  <img src="./images/earth.png" alt="地球" loading="lazy">
</picture>

图片命名规范

推荐的命名方式：

✅ 好的命名
- hero-banner.png
- user-avatar-john.jpg
- diagram-architecture.svg

❌ 不好的命名
- IMG_1234.jpg
- 屏幕截图.png
- image (1).png

图片 Alt 文本

始终为图片添加有意义的 alt 文本：

<!-- ❌ 不好 -->
![图片](./images/earth.png)

<!-- ✅ 好 -->
![地球从太空中的视角，显示蓝色海洋和白色云层](./images/earth.png)

CDN 加速（可选）

对于大量图片，可以使用 CDN：

使用 Cloudflare Images

![描述](https://imagedelivery.net/your-account/image-id/public)

使用 imgix

![描述](https://your-domain.imgix.net/path/to/image.jpg?w=800&auto=format)

图片懒加载

在 Markdown 中使用 HTML 实现懒加载：

<img src="./images/earth.png" alt="地球" loading="lazy" width="800" height="600">

完整示例

下面是一个包含多种图片使用方式的示例：

标题图片

文章标题图

内联图片

这是一段文字，其中包含一个小图标 图标 在文字中间。

带链接的图片

点击查看大图

图片说明

地球
图1：地球从国际空间站拍摄

部署注意事项

1. 构建时

npm run build

Astro 会：

  • 优化 src/ 中引用的图片
  • 复制 public/ 中的文件到 dist/
  • 生成响应式图片变体

2. Docker 部署

确保 Dockerfile 包含图片：

# 复制所有源文件（包括图片）
COPY . .

# 构建会处理图片
RUN npm run build

3. Git LFS（大文件）

如果有大量大图片，使用 Git LFS：

# 安装 Git LFS
git lfs install

# 追踪图片文件
git lfs track "*.png"
git lfs track "*.jpg"

# 提交
git add .gitattributes
git commit -m "Add Git LFS"

性能检查清单

  • 图片已压缩
  • 使用了适当的格式
  • 添加了 alt 文本
  • 大图片使用懒加载
  • 考虑使用 CDN
  • 响应式图片（多尺寸）

总结

推荐方案：

  1. 博客配图：放在 src/content/blog/images/，使用相对路径
  2. 网站资源：放在 public/images/，使用绝对路径
  3. 需要优化：在 .astro 文件中使用 <Image> 组件

这样可以获得最佳的性能和管理体验！

参考资源

返回博客列表