Markdown 图片: 发布前避免路径错误和 alt 缺失
很多人搜索 markdown image，真正想解决的不是语法本身，而是“把截图、示意图、知识库配图稳定发出去，不要上线后才发现坏图”。
Quick answer
先在 Markdown Editor 写图片语法，再在 Markdown Preview 里预览，因为图片类问题通常一起出现: 路径可能错、alt 可能空、页面里的实际显示也可能不对。
为什么图片一定要先 preview 再发布
图片语法很短，但发布风险并不小。
- docs 场景里，步骤截图一旦失效，说明就断了
- 博客场景里，alt 太弱会让图片失去说明价值
- 知识库场景里，宽度和余白一乱，答案整体都会变难读
所以，图片是否“可交付”，不应该只看源码，而应该看 Markdown Preview 里的真实渲染结果。
显示效果校验流程
先掌握这条图片语法
最小可用写法:
这一行同时决定了三件事:
- alt: 图片在说明什么
- path: 渲染器去哪里找图
- display: 图片在页面里最终怎么显示
路径怎么选
大多数情况下只会遇到两类路径:
- 相对路径:
 - 站点根路径:
如果拿不准，最好的办法不是猜，而是直接 preview。源码里看起来没问题，不代表发布路由下一样没问题。
alt 要写“这张图证明了什么”
alt 不应该只是文件名，也不该只有一个模糊单词。
更好的写法:
较弱的写法:
在 docs、博客、知识库场景里，读者需要知道这张图在证明什么 UI 状态、哪个步骤结果、或哪段知识点。
docs、博客、知识库里的典型用法
- docs: 展示正确的按钮或配置位置
- 博客: 插入一张说明流程的图，但不压坏正文节奏
- 知识库: 用截图快速定位故障点
所以图片工作流不只是语法题，它也属于 Markdown 平台工作流 Hub 里的发布链路判断。
两个常见错误和修正方式
错误 1: 路径写错
错误示例:
如果真实目录是 images，preview 会立刻暴露坏图问题。
修正:
错误 2: alt 为空
错误示例:
图片即使能显示，读者也不知道它在帮助确认什么。
修正:
发布前 preview 清单
在 Markdown Preview 里至少看这 5 件事:
- 图片能正常加载
- 发布路由下路径仍然有效
- 图片前后余白自然
- alt 能说明图片用途
- 快速浏览时，这张图确实增强了页面理解
Final takeaway
Markdown 图片真正的难点不是写 ![]()，而是保证发布后的真实显示稳定。Markdown Editor 负责写， Markdown Preview 负责在发布前把路径、alt 和布局问题拦下来。
打开 Markdown Preview，在发布前确认图片加载和显示效果。
Internal workflow links
- 写作入口: Markdown Editor
- 渲染校验: Markdown Preview
- 发布语境: Markdown 平台工作流 Hub
FAQ
Markdown 里怎么插入图片？
使用 ，然后在预览里检查最终渲染。
图片不显示通常是什么原因？
常见原因是路径错误、资源没有出现在发布路由下，或者发布前没有做 preview 校验。
alt 文本一定要写吗？
对 docs、博客、知识库里有实际说明作用的图片来说，应该写，而且要说明这张图在证明什么。