1、Markdown 图片的基本写法#

Markdown 中插入图片通常是：

1
![图片说明](./images/demo.png)

方括号里的内容就是 alt 文本。它不是给搜索引擎随便堆关键词的地方，而是图片无法正常观看时的替代说明。

如果只是这样写：

1
![](./images/error.png)

图片一旦加载失败，读者就很难知道这里原本想表达什么。

2、不要写成无意义描述#

有些 alt 看起来写了，但实际帮助不大：

1
![图片](./images/chart.png)
2
![截图](./images/terminal.png)
3
![示意图](./images/flow.png)

这些词太泛了。更好的写法是说明图片内容和上下文：

1
![终端中显示 ModuleNotFoundError 的报错位置](./images/import-error.png)
2
![按日期统计订单数量后的柱状图结果](./images/order-chart.png)
3
![前端请求经过 Nginx 转发到后端接口的流程](./images/proxy-flow.png)

读者即使看不到图片，也能大致知道这里展示的是什么。

3、截图类图片写关键结论#

技术博客里经常会放终端截图、网页截图或配置界面截图。写 alt 时不要只写“终端截图”，最好写出截图里最重要的信息。

例如一张构建成功截图，可以写：

1
![pnpm build 执行完成并显示生成静态页面数量](./images/build-success.png)

如果截图是报错信息，可以写：

1
![浏览器控制台显示接口返回 404 的错误信息](./images/api-404.png)

这样后面回看文章时，也能更快理解图片为什么放在这里。

4、流程图类图片写结构关系#

如果图片是流程图，alt 可以简要描述节点关系：

1
![数据从 CSV 读取后经过清洗、分组统计并导出 Excel 的流程](./images/data-flow.png)

不需要把图里的所有文字完整重复一遍，但要把主线讲清楚。

如果流程比较复杂，可以在图片下面再补一段正文说明，而不是把所有信息塞进 alt。

5、整理旧文章时的检查清单#

给旧博客补 alt 时，我会按这几个问题检查：

• 图片是否有方括号说明。
• 说明是否比“图片”“截图”更具体。
• 是否写出了图片和当前段落的关系。
• 如果图片加载失败，读者能否继续理解文章。
• 同一篇文章里的图片说明是否风格一致。

可以先用搜索找出空 alt：

1
grep -R \"!\\[\\]\" src/content/posts

如果是在 Windows PowerShell 里，也可以用：

1
Select-String -Path "src/content/posts/**/*.md" -Pattern "!\[\]"

6、我的写法原则#

我现在会把 alt 当成一句短说明，而不是标题。一般控制在一行内，优先写清楚三件事：

1
图片类型 + 关键内容 + 和文章步骤的关系

比如：

1
![Pagefind 构建日志中提示跳过 guestbook 页面](./images/pagefind-warning.png)

这句话说明了图片来自哪里、显示了什么、为什么值得放进文章。

小结#

博客图片 alt 文本不是装饰项。它可以让文章在图片加载失败、读屏阅读、后期维护时都更容易理解。

我的最低要求是：不要空着，不要只写“图片”，尽量写出图片的关键信息和上下文。这个习惯不会增加太多写作成本，但能明显提升文章的可读性和可维护性。