1. 先别急着贴图认清 Markdown 图片的本质很多人第一次在 Markdown 里插入图片都是被“简单”两个字骗进来的。搜了一圈语法发现无非是这种格式于是信心满满地开始写。结果图片要么在本地好好的换台电脑就变叉号要么发给别人对方压根看不到要么导出 PDF 时图片神秘失踪。这些问题我当年全踩过而且踩得结结实实。想搞清楚 Markdown 的图片机制先要接受一个事实Markdown 本身并不“存储”图片它只负责“引用”图片。你写下的那行语法本质上是一张“指路牌”告诉渲染器“去这个地址把图片找出来展示”。这个地址可以是本地磁盘上的一个路径也可以是互联网上的一个 URL。这就引出了很多新手误解的第一个根源很多人以为把.md文件发给别人图片就跟着过去了。实际上你发出去的是一个“指路牌”而图片文件还留在你的硬盘里。对方拿到指路牌但顺着地址找不到图片自然就显示成一张裂开的图标。理解了这个本质后面的一切问题都好解释了为什么换了目录图片就失效因为相对路径变了指路牌失效。为什么 Typora 里看着好好的用 VSCode 打开就裂了因为不同编辑器的默认工作目录不一样。为什么导出 PDF 时图片飞了因为渲染器顺着地址找不到资源。一句话总结Markdown 图片管理的核心不是“写语法”而是“管好图片文件本身的存放位置和引用方式”。语法三分钟能学会但管理图片的思维方式决定你后面会不会踩坑。2. 本地图片管理从“能用”到“好用”的关键路径2.1 图片到底该放在哪里最入门、也最不容易出错的方案是“图片文件夹 相对路径引用”。具体操作是在你的项目根目录下建一个assets或images文件夹把文章里用到的所有图片丢进去然后在 Markdown 中用相对路径引用。我见过很多初学者喜欢用绝对路径比如C:\Users\张三\Desktop\项目\图片\封面.png。这个做法在你自己电脑上没问题但一旦文件夹移动、重命名或者你把整个项目打包发给别人图片全会裂开——因为这些“指路牌”依然指向你电脑上那个已经不存在的位置。正确的引用方式是这样的注意那个./它表示“当前文件所在目录”。意思就是在当前文件同级的assets文件夹里找cover.png。这样整个项目文件夹无论拷到哪里只要内部的相对结构不变图片就都能正常显示。如果在引用子目录下的文件时需要用到../表示“上一级目录”。比如这条语句的意思就很明确从当前文件所在位置往上一层进入assets/chapter2/目录找example.png。2.2 相对路径里的“隐形杀手”空格和中文相对路径解决了“文件挪了位置导致图片失效”的问题但还藏着一个让人抓狂的坑——路径里的空格和中文。先说空格。如果你用 Windows路径中很可能带有空格比如C:\My Documents\My Images\图1.png。在某些 Markdown 渲染器中路径中的空格会被截断导致图片无法加载。处理办法有几种用%20转义空格如./My%20Documents/photo.png这是 URL 编码方式用尖括号包裹整个路径如这是 Markdown 官方推荐的解法之一最省事的做法建文件夹和文件名时一律不用空格用连字符-或下划线_替代至于中文名更令人头疼。很多 Markdown 渲染器默认按 UTF-8 解析路径但一些老旧的渲染组件或第三方导出工具可能按系统默认编码处理于是中文路径就会变成乱码。最稳妥的做法是图片文件名统一用英文小写 数字 连字符例如chapter1-cover.png。这点看起来不起眼但能避免很多莫名其妙的问题。注意如果你用 Typora还应该在偏好设置里检查“图片插入”相关选项——建议开启“复制图片到 ./assets 文件夹”和“优先使用相对路径”这样拖拽插入图片时Typora 会自动帮你复制文件并生成正确的相对路径引用。3. 图床方案让图片突破“本地磁盘”的限制3.1 什么时候需要用图床本地路径解决方案最大痛点是图片跟着文档走但文档不一定永远只在你电脑上。当你需要把 Markdown 内容发布到博客、知乎、公众号或者分享给同事在线协作时本地图片就彻底失效了——因为对方的环境里没有你硬盘上那些文件。这时候就需要“图床”把图片上传到一个公网可达的服务器上得到一个固定 URL然后在 Markdown 里引用这个 URL。打个简单的比方本地图片就像你把自己家的钥匙递给朋友前提是朋友得站在你家门口才能开门图床则像是你把行李寄存到一个全球连锁的储物柜然后把取件码发给朋友朋友在任何一个城市都能取到。3.2 主流图床方案怎么选图床方案从“省心”到“折腾”可以排个序方案优点缺点适合场景GitHub jsDelivr CDN免费、稳定、国内访问速度尚可仓库必须公开、有被“和谐”风险技术博客、个人笔记阿里云/腾讯云 OSS速度快、稳定性高有费用按存储和流量计费流量较大的站点Cloudflare R2免费额度大、无需 CDN 配置国内访问速度一般个人项目、海外部署七牛云国内访问快、有免费额度需要备案域名才能绑自定义域名国内博客SM.MS / 路过图床等公共图床零配置、上手快可靠性无法保障随时可能挂临时分享、演示我自己在项目里用的是 GitHub jsDelivr 组合。理由很简单免费、稳定而且图片托管在 GitHub 仓库里天然有一个版本管理。每次上传图片就是git push一下流程很顺。如果你有技术背景这个方案几乎是零成本起步。3.3 图床上传和引用的标准姿势以 GitHub 图床为例操作逻辑是这样的建一个公开仓库比如image-host把图片文件推送到仓库可以用 Git 命令行也可以用 GitHub 网页直接上传拿到原始文件链接拼接成 CDN 加速链接格式原始链接https://github.com/用户名/image-host/blob/main/images/photo.pngCDN 链接https://cdn.jsdelivr.net/gh/用户名/image-hostmain/images/photo.png然后你在 Markdown 里这么写这样一来图片不再依赖你的本地文件不管文档换到哪台设备、发给谁只要对方能联网图片就能正常加载。3.4 用 PicGo 让“传图”变成“一键操作”手动去 GitHub 网页上传图片再复制链接粘贴到 Markdown这个流程听起来还行但一旦文章里图片超过十张你就会开始暴躁。这时候需要自动化工具我用的是 PicGo它是目前用得最多的图床管理客户端之一。PicGo 支持的图床种类很全GitHub、阿里云 OSS、腾讯云 COS、SM.MS、七牛云、Imgur 都有还支持自定义插件扩展。安装配置完成后你只需要做两件事全局快捷键我设置为CtrlShiftP截图或复制图片后按快捷键图片自动上传并返回 Markdown 格式链接且已复制到系统剪贴板直接黏贴进文档、图形化、可视化、拖拽上传这些功能全都有。配合 Typora 的“自定义图片上传服务”你甚至可以在 Typora 里拖入一张本地图片它自动帮你上传到图床并替换为远程链接。这一步体验做扎实了整个写作流就很舒服了。4. 图片尺寸、居中和多图排版的“法外之地”4.1 标准语法搞不定的排版需求很多初学 Markdown 的人会有一个疑问为什么标准语法里没有“设置图片宽度”“居中”这些选项答案很简单因为 Markdown 的哲学是“只管内容不管排版”它把排版交给 CSS以及导出时的 PDF 或 HTML 模板去处理。但这不意味着 Markdown 里什么都不能做。Markdown 本身兼容 HTML所以你可以直接用 HTML 标签来控制图片显示。比如你需要把一张宽度过大的截图缩小到合适尺寸可以在 Markdown 里这样写img src./assets/screenshot.png alt运行截图 width600需要居中加上样式div styletext-align: center; img src./assets/screenshot.png alt运行截图 width600 /div这个语法在 Typora、VSCode、大多数在线 Markdown 编辑器里都是能正常渲染的。唯一要注意的是某些纯 Markdown 渲染器比如 GitHub 的 README出于安全考虑会过滤 HTML 标签导致这些样式失效。所以在 GitHub 上发布内容时要确认这些标签不会被过滤。4.2 不同编辑器的尺寸控制差异各编辑器的实现有细节差异这点需要特别留意。Typora 支持在图片 URL 后面添加尺寸参数这个写法是 Typora 特有的语法在 Typora 中生效但是放到其他编辑器中会失效可能显示出奇怪的文本。所以如果项目的通用性要求高建议还是用 HTML 标签。VSCode 配合 Markdown Preview Enhanced 插件时则可以通过 CSS 覆盖控制图片最大宽度比如在插件的样式文件里写img { max-width: 100%; }这样所有图片都不会超出阅读区域的宽度移动端阅读体验会好很多。提示如果你写的内容会在微信公众号等平台上使用注意这些平台有自己的图片上传通道复制粘贴 Markdown 里的远程图片链接往往不能直接引用需要先下载图片再上传到平台后台。这时候我用一个技巧本地用 Markdown 写好导出时下载所有图片然后逐张上传到公众号后台再在编辑器里排布。虽然麻烦一点但可控性最高。5. 从 Markdown 到 Word/PDF图片导出的坑与解法5.1 PDF 导出时的图片失真和漂移写 Markdown 文档大多数时候是为了自己的阅读和记录但总免不了要交付——报告、简历、说明书。这时候就会遇到一个经典问题Markdown 里看着不错的图片导出 PDF 后却惨不忍睹。图片在 PDF 里会有三个典型毛病清晰度不够、位置漂移、甚至直接丢失。针对不同情况解决方法也不同先说清晰度。Markdown 里常见的位图JPG、PNG分辨率是固定的如果原图很小比如 400×300强制拉大显示就会糊。解决办法是在写作时插入图片尽量使用原始分辨率足够高的图片或者使用 SVG 这类矢量格式。Typora 原生支持 SVG 渲染部分旧版本需要安装扩展在导出 PDF 时矢量图可以无损缩放。再说图片漂移。很多 Markdown 渲染器在导出 PDF 时使用类似网页的流式布局图片可能被自动推到下一页。尤其是在图片紧跟表格或列表时漂移问题更容易发生。减少漂移的一个技巧是在图片前后插入一个空行并且给图片加上“说明书”性质的描述文字让它成为一个独立段落。最后是图片丢失。这个情况多发生在使用 Typora 导出 PDF 时如果图片链接是“失效的相对路径”或“本地绝对路径”导出组件找不到资源就会留一个空白区域。排查方法是先在 Typora 里试着点击图片链接看能否在文件管理器中定位到图片。5.2 Word 转换Pandoc 是绕不开的门槛Markdown 转 Word 至今没有哪家编辑器能做得完美最可靠的还是 Pandoc 这个开源老将。Pandoc 的思想很简单它是一种“格式交换机”能把 Markdown 转成 docx、PDF、HTML、Epub 等几乎任何文件格式。安装 Pandoc 后在命令行执行pandoc input.md -o output.docx一条命令就能完成转换。但这里有个细节Pandoc 转换时Markdown 里的本地图片无法自动带进 Word。Pandoc 默认情况下不会嵌入图片文件本身而是在 Word 中保留一条图片链接。如果 Word 在打开时无法访问该链接图片就会消失。解决办法是在转 Word 前先确保图片路径是相对路径且有效并且 Pandoc 是在项目目录下执行的。更稳的办法是先把图片上传到图床用 URL 引用这样 Pandoc 转出来的 Word 会自动下载并嵌入这些图片。如果你的工作流里需要频繁转换 Markdown 到 Word建议搭配一个自动化工具如 Coze 或 n8n搭建一个简单的“Markdown 转 Word 工作流”输入 Markdown 文本 → 解析图片链接 → 下载图片 → 调用 Pandoc 生成 Word → 把结果反馈回来。这个思路在内部生产力工具里特别实用我测试过能把平均 5 分钟的转换时间压缩到数十秒。5.3 用 Markdown Preview Enhanced 导出 PDF 踩过的乱码坑如果你是 VSCode 用户大概率用过 Markdown Preview EnhancedMPE这个插件。它不仅支持预览还能导出 PDF、HTML、PNG 等多种格式。这个插件最常用的导出方式是借助 Chrome 无头浏览器来渲染但有些人反馈导出 PDF 时中文乱码或排版错乱。我在排查中发现绝大多数乱码问题出在字体上Chrome 无头浏览器渲染时没有调用系统中文字体。解决方案有两种修改 MPE 的导出配置在导出命令中指定字体选项或者给 Markdown 文件头加 YAML front matter使用fontfamily指定字体安装 Prince 后改用 Prince 渲染引擎导出 PDF没错MPE 支持多种 PDF 导出路径Prince 是其中之一。Prince 对中文文本的排版支持更好在“导出 PDF 乱码”问题上比 Chrome 方案稳定不少。但 Prince 本身是商业软件非商业使用免费安装时要留意许可证条款。6. 常见问题与排查技巧实录在实际写 Markdown 文档的过程中我积攒了不少经验也踩过非常多坑。下面这些问题基本可以称得上“每个 Markdown 用户都会遇到”我把排查思路写在这里方便大家直接照着查。6.1 图片显示为裂开的图标排查步骤按照下面顺序做检查引用路径大小写是否和实际文件名一致。Windows 文件名不区分大小写但 Linux、macOS 和很多在线渲染器区分所以最好全部用小写。检查文件扩展名是否写对。常见错误比如把.PNG写成.png虽然 Windows 下能打开但在线服务不一定兼容。检查相对路径是否正确。在渲染器里右键查看图片地址确认它指向的位置确实有图片。检查是否需要网络。如果是图床 URL先确认图片链接在浏览器里能否直接打开。打不开就说明图床失效需要换图床或重新上传。6.2 图片在 Typora 正常但 GitHub 显示异常这种情况大多和 HTML 标签有关。GitHub 的 Markdown 渲染安全策略比较严会过滤掉一些 HTML 标签和属性比如img width里的 width 属性。如果 GitHub 上图片没显示优先考虑换成标准的语法。6.3 Typora 导入本地图片后移动目录导致文件“丢失”Typora 默认并不会自动拷贝图片到指定文件夹。如果你勾选了“复制图片到 assets 目录”却发现图片依然丢失多半是“插入图片时”选项里的“对本地图片位置应用规则”勾选状态不对或者移动文件时没有连同 assets 文件夹一起移动。建议每次整理文件后手动检查一遍图片引用是否仍然有效。6.4 前端项目里 Markdown 图片被拦截如果你在公司内部或自己搭建的网站上用 Markdown 渲染器展示文章比如 VitePress 或 Docsify图片可能会遇到防盗链问题。有些图床会校验请求来源非白名单域名直接拒绝返回图片。排查方式是在浏览器控制台查看图片请求的状态码如果是 403就用响应头确认是否被防盗链拦截然后去图床后台把当前域名加入白名单。6.5 导出的 Word 文档里图片排版混乱Pandoc 转换时图片默认的对齐方式、宽度控制可能和 Word 的默认样式冲突。可以在转换时指定一个参考文档reference docx 模板里面预置你想要的图片样式。这样 Pandoc 会把 Markdown 图片按模板格式排布整体会整齐很多。pandoc input.md -o output.docx --reference-docmy-reference.docx7. 结合我个人的使用习惯分享几个“非主流”但确实生效的偏方聊了这么多最后讲几个我私藏的小技巧。这些技巧不一定能写进官方文档但实测下来相当好用。第一个技巧给图片加“替代文本”不是可选项是必选项。写时描述尽量写得具体一些。虽然你平时预览时看不到它的作用但一旦图片加载失败读者看到的就是这段描述同时它也是无障碍阅读和 SEO 的重要一环。别图省事随手写个“img1”或者直接留空。第二个技巧截图的透明背景要留意。尤其在深色环境下编辑截图如果是白底贴到深色 Markdown 预览里会显得很突兀。用支持“窗口透明”截图的工具比如 Snipaste截图时保留透明背景图片插入文档后效果干净很多。第三个技巧给图片建立命名规范。我自己的规范是“日期-模块-序号”例如20250612-deploy-01.png。这样的好处是即使以后不用 Markdown改用 Notion、语雀等工具这个命名习惯依然通用文件管理不会乱。第四个技巧批量处理图片尺寸靠工具不靠手写 HTML。如果一篇文章里有二十张截图逐一写img width会很累。我通常用npx squoosh-cli或 ImageMagick 批量压缩和调整图片尺寸然后把 Markdown 里的图片统一用 CSS 控制展示宽度。这样图片文件体积小预览体验却不打折。以上这些内容都是我在各种 Markdown 项目中踩坑、填坑、再踩坑的经验总结。图片使用这件事看起来非常简单但真正规范起来涉及文件组织、路径管理、图床选型、导出链路等多个环节。每次觉得自己已经搞明白了就会在一个新场景下遇到新问题。我个人最大的体会是不要迷信某一种方案“万能”先弄清楚自己的使用场景——是个人笔记团队协作还是对外发布再针对性地选一种管理方式并坚持使用这样图片才会真的成为你写作路上的助力而不是麻烦制造机。
Markdown图片管理全攻略：从本地路径到图床与导出避坑
1. 先别急着贴图认清 Markdown 图片的本质很多人第一次在 Markdown 里插入图片都是被“简单”两个字骗进来的。搜了一圈语法发现无非是这种格式于是信心满满地开始写。结果图片要么在本地好好的换台电脑就变叉号要么发给别人对方压根看不到要么导出 PDF 时图片神秘失踪。这些问题我当年全踩过而且踩得结结实实。想搞清楚 Markdown 的图片机制先要接受一个事实Markdown 本身并不“存储”图片它只负责“引用”图片。你写下的那行语法本质上是一张“指路牌”告诉渲染器“去这个地址把图片找出来展示”。这个地址可以是本地磁盘上的一个路径也可以是互联网上的一个 URL。这就引出了很多新手误解的第一个根源很多人以为把.md文件发给别人图片就跟着过去了。实际上你发出去的是一个“指路牌”而图片文件还留在你的硬盘里。对方拿到指路牌但顺着地址找不到图片自然就显示成一张裂开的图标。理解了这个本质后面的一切问题都好解释了为什么换了目录图片就失效因为相对路径变了指路牌失效。为什么 Typora 里看着好好的用 VSCode 打开就裂了因为不同编辑器的默认工作目录不一样。为什么导出 PDF 时图片飞了因为渲染器顺着地址找不到资源。一句话总结Markdown 图片管理的核心不是“写语法”而是“管好图片文件本身的存放位置和引用方式”。语法三分钟能学会但管理图片的思维方式决定你后面会不会踩坑。2. 本地图片管理从“能用”到“好用”的关键路径2.1 图片到底该放在哪里最入门、也最不容易出错的方案是“图片文件夹 相对路径引用”。具体操作是在你的项目根目录下建一个assets或images文件夹把文章里用到的所有图片丢进去然后在 Markdown 中用相对路径引用。我见过很多初学者喜欢用绝对路径比如C:\Users\张三\Desktop\项目\图片\封面.png。这个做法在你自己电脑上没问题但一旦文件夹移动、重命名或者你把整个项目打包发给别人图片全会裂开——因为这些“指路牌”依然指向你电脑上那个已经不存在的位置。正确的引用方式是这样的注意那个./它表示“当前文件所在目录”。意思就是在当前文件同级的assets文件夹里找cover.png。这样整个项目文件夹无论拷到哪里只要内部的相对结构不变图片就都能正常显示。如果在引用子目录下的文件时需要用到../表示“上一级目录”。比如这条语句的意思就很明确从当前文件所在位置往上一层进入assets/chapter2/目录找example.png。2.2 相对路径里的“隐形杀手”空格和中文相对路径解决了“文件挪了位置导致图片失效”的问题但还藏着一个让人抓狂的坑——路径里的空格和中文。先说空格。如果你用 Windows路径中很可能带有空格比如C:\My Documents\My Images\图1.png。在某些 Markdown 渲染器中路径中的空格会被截断导致图片无法加载。处理办法有几种用%20转义空格如./My%20Documents/photo.png这是 URL 编码方式用尖括号包裹整个路径如这是 Markdown 官方推荐的解法之一最省事的做法建文件夹和文件名时一律不用空格用连字符-或下划线_替代至于中文名更令人头疼。很多 Markdown 渲染器默认按 UTF-8 解析路径但一些老旧的渲染组件或第三方导出工具可能按系统默认编码处理于是中文路径就会变成乱码。最稳妥的做法是图片文件名统一用英文小写 数字 连字符例如chapter1-cover.png。这点看起来不起眼但能避免很多莫名其妙的问题。注意如果你用 Typora还应该在偏好设置里检查“图片插入”相关选项——建议开启“复制图片到 ./assets 文件夹”和“优先使用相对路径”这样拖拽插入图片时Typora 会自动帮你复制文件并生成正确的相对路径引用。3. 图床方案让图片突破“本地磁盘”的限制3.1 什么时候需要用图床本地路径解决方案最大痛点是图片跟着文档走但文档不一定永远只在你电脑上。当你需要把 Markdown 内容发布到博客、知乎、公众号或者分享给同事在线协作时本地图片就彻底失效了——因为对方的环境里没有你硬盘上那些文件。这时候就需要“图床”把图片上传到一个公网可达的服务器上得到一个固定 URL然后在 Markdown 里引用这个 URL。打个简单的比方本地图片就像你把自己家的钥匙递给朋友前提是朋友得站在你家门口才能开门图床则像是你把行李寄存到一个全球连锁的储物柜然后把取件码发给朋友朋友在任何一个城市都能取到。3.2 主流图床方案怎么选图床方案从“省心”到“折腾”可以排个序方案优点缺点适合场景GitHub jsDelivr CDN免费、稳定、国内访问速度尚可仓库必须公开、有被“和谐”风险技术博客、个人笔记阿里云/腾讯云 OSS速度快、稳定性高有费用按存储和流量计费流量较大的站点Cloudflare R2免费额度大、无需 CDN 配置国内访问速度一般个人项目、海外部署七牛云国内访问快、有免费额度需要备案域名才能绑自定义域名国内博客SM.MS / 路过图床等公共图床零配置、上手快可靠性无法保障随时可能挂临时分享、演示我自己在项目里用的是 GitHub jsDelivr 组合。理由很简单免费、稳定而且图片托管在 GitHub 仓库里天然有一个版本管理。每次上传图片就是git push一下流程很顺。如果你有技术背景这个方案几乎是零成本起步。3.3 图床上传和引用的标准姿势以 GitHub 图床为例操作逻辑是这样的建一个公开仓库比如image-host把图片文件推送到仓库可以用 Git 命令行也可以用 GitHub 网页直接上传拿到原始文件链接拼接成 CDN 加速链接格式原始链接https://github.com/用户名/image-host/blob/main/images/photo.pngCDN 链接https://cdn.jsdelivr.net/gh/用户名/image-hostmain/images/photo.png然后你在 Markdown 里这么写这样一来图片不再依赖你的本地文件不管文档换到哪台设备、发给谁只要对方能联网图片就能正常加载。3.4 用 PicGo 让“传图”变成“一键操作”手动去 GitHub 网页上传图片再复制链接粘贴到 Markdown这个流程听起来还行但一旦文章里图片超过十张你就会开始暴躁。这时候需要自动化工具我用的是 PicGo它是目前用得最多的图床管理客户端之一。PicGo 支持的图床种类很全GitHub、阿里云 OSS、腾讯云 COS、SM.MS、七牛云、Imgur 都有还支持自定义插件扩展。安装配置完成后你只需要做两件事全局快捷键我设置为CtrlShiftP截图或复制图片后按快捷键图片自动上传并返回 Markdown 格式链接且已复制到系统剪贴板直接黏贴进文档、图形化、可视化、拖拽上传这些功能全都有。配合 Typora 的“自定义图片上传服务”你甚至可以在 Typora 里拖入一张本地图片它自动帮你上传到图床并替换为远程链接。这一步体验做扎实了整个写作流就很舒服了。4. 图片尺寸、居中和多图排版的“法外之地”4.1 标准语法搞不定的排版需求很多初学 Markdown 的人会有一个疑问为什么标准语法里没有“设置图片宽度”“居中”这些选项答案很简单因为 Markdown 的哲学是“只管内容不管排版”它把排版交给 CSS以及导出时的 PDF 或 HTML 模板去处理。但这不意味着 Markdown 里什么都不能做。Markdown 本身兼容 HTML所以你可以直接用 HTML 标签来控制图片显示。比如你需要把一张宽度过大的截图缩小到合适尺寸可以在 Markdown 里这样写img src./assets/screenshot.png alt运行截图 width600需要居中加上样式div styletext-align: center; img src./assets/screenshot.png alt运行截图 width600 /div这个语法在 Typora、VSCode、大多数在线 Markdown 编辑器里都是能正常渲染的。唯一要注意的是某些纯 Markdown 渲染器比如 GitHub 的 README出于安全考虑会过滤 HTML 标签导致这些样式失效。所以在 GitHub 上发布内容时要确认这些标签不会被过滤。4.2 不同编辑器的尺寸控制差异各编辑器的实现有细节差异这点需要特别留意。Typora 支持在图片 URL 后面添加尺寸参数这个写法是 Typora 特有的语法在 Typora 中生效但是放到其他编辑器中会失效可能显示出奇怪的文本。所以如果项目的通用性要求高建议还是用 HTML 标签。VSCode 配合 Markdown Preview Enhanced 插件时则可以通过 CSS 覆盖控制图片最大宽度比如在插件的样式文件里写img { max-width: 100%; }这样所有图片都不会超出阅读区域的宽度移动端阅读体验会好很多。提示如果你写的内容会在微信公众号等平台上使用注意这些平台有自己的图片上传通道复制粘贴 Markdown 里的远程图片链接往往不能直接引用需要先下载图片再上传到平台后台。这时候我用一个技巧本地用 Markdown 写好导出时下载所有图片然后逐张上传到公众号后台再在编辑器里排布。虽然麻烦一点但可控性最高。5. 从 Markdown 到 Word/PDF图片导出的坑与解法5.1 PDF 导出时的图片失真和漂移写 Markdown 文档大多数时候是为了自己的阅读和记录但总免不了要交付——报告、简历、说明书。这时候就会遇到一个经典问题Markdown 里看着不错的图片导出 PDF 后却惨不忍睹。图片在 PDF 里会有三个典型毛病清晰度不够、位置漂移、甚至直接丢失。针对不同情况解决方法也不同先说清晰度。Markdown 里常见的位图JPG、PNG分辨率是固定的如果原图很小比如 400×300强制拉大显示就会糊。解决办法是在写作时插入图片尽量使用原始分辨率足够高的图片或者使用 SVG 这类矢量格式。Typora 原生支持 SVG 渲染部分旧版本需要安装扩展在导出 PDF 时矢量图可以无损缩放。再说图片漂移。很多 Markdown 渲染器在导出 PDF 时使用类似网页的流式布局图片可能被自动推到下一页。尤其是在图片紧跟表格或列表时漂移问题更容易发生。减少漂移的一个技巧是在图片前后插入一个空行并且给图片加上“说明书”性质的描述文字让它成为一个独立段落。最后是图片丢失。这个情况多发生在使用 Typora 导出 PDF 时如果图片链接是“失效的相对路径”或“本地绝对路径”导出组件找不到资源就会留一个空白区域。排查方法是先在 Typora 里试着点击图片链接看能否在文件管理器中定位到图片。5.2 Word 转换Pandoc 是绕不开的门槛Markdown 转 Word 至今没有哪家编辑器能做得完美最可靠的还是 Pandoc 这个开源老将。Pandoc 的思想很简单它是一种“格式交换机”能把 Markdown 转成 docx、PDF、HTML、Epub 等几乎任何文件格式。安装 Pandoc 后在命令行执行pandoc input.md -o output.docx一条命令就能完成转换。但这里有个细节Pandoc 转换时Markdown 里的本地图片无法自动带进 Word。Pandoc 默认情况下不会嵌入图片文件本身而是在 Word 中保留一条图片链接。如果 Word 在打开时无法访问该链接图片就会消失。解决办法是在转 Word 前先确保图片路径是相对路径且有效并且 Pandoc 是在项目目录下执行的。更稳的办法是先把图片上传到图床用 URL 引用这样 Pandoc 转出来的 Word 会自动下载并嵌入这些图片。如果你的工作流里需要频繁转换 Markdown 到 Word建议搭配一个自动化工具如 Coze 或 n8n搭建一个简单的“Markdown 转 Word 工作流”输入 Markdown 文本 → 解析图片链接 → 下载图片 → 调用 Pandoc 生成 Word → 把结果反馈回来。这个思路在内部生产力工具里特别实用我测试过能把平均 5 分钟的转换时间压缩到数十秒。5.3 用 Markdown Preview Enhanced 导出 PDF 踩过的乱码坑如果你是 VSCode 用户大概率用过 Markdown Preview EnhancedMPE这个插件。它不仅支持预览还能导出 PDF、HTML、PNG 等多种格式。这个插件最常用的导出方式是借助 Chrome 无头浏览器来渲染但有些人反馈导出 PDF 时中文乱码或排版错乱。我在排查中发现绝大多数乱码问题出在字体上Chrome 无头浏览器渲染时没有调用系统中文字体。解决方案有两种修改 MPE 的导出配置在导出命令中指定字体选项或者给 Markdown 文件头加 YAML front matter使用fontfamily指定字体安装 Prince 后改用 Prince 渲染引擎导出 PDF没错MPE 支持多种 PDF 导出路径Prince 是其中之一。Prince 对中文文本的排版支持更好在“导出 PDF 乱码”问题上比 Chrome 方案稳定不少。但 Prince 本身是商业软件非商业使用免费安装时要留意许可证条款。6. 常见问题与排查技巧实录在实际写 Markdown 文档的过程中我积攒了不少经验也踩过非常多坑。下面这些问题基本可以称得上“每个 Markdown 用户都会遇到”我把排查思路写在这里方便大家直接照着查。6.1 图片显示为裂开的图标排查步骤按照下面顺序做检查引用路径大小写是否和实际文件名一致。Windows 文件名不区分大小写但 Linux、macOS 和很多在线渲染器区分所以最好全部用小写。检查文件扩展名是否写对。常见错误比如把.PNG写成.png虽然 Windows 下能打开但在线服务不一定兼容。检查相对路径是否正确。在渲染器里右键查看图片地址确认它指向的位置确实有图片。检查是否需要网络。如果是图床 URL先确认图片链接在浏览器里能否直接打开。打不开就说明图床失效需要换图床或重新上传。6.2 图片在 Typora 正常但 GitHub 显示异常这种情况大多和 HTML 标签有关。GitHub 的 Markdown 渲染安全策略比较严会过滤掉一些 HTML 标签和属性比如img width里的 width 属性。如果 GitHub 上图片没显示优先考虑换成标准的语法。6.3 Typora 导入本地图片后移动目录导致文件“丢失”Typora 默认并不会自动拷贝图片到指定文件夹。如果你勾选了“复制图片到 assets 目录”却发现图片依然丢失多半是“插入图片时”选项里的“对本地图片位置应用规则”勾选状态不对或者移动文件时没有连同 assets 文件夹一起移动。建议每次整理文件后手动检查一遍图片引用是否仍然有效。6.4 前端项目里 Markdown 图片被拦截如果你在公司内部或自己搭建的网站上用 Markdown 渲染器展示文章比如 VitePress 或 Docsify图片可能会遇到防盗链问题。有些图床会校验请求来源非白名单域名直接拒绝返回图片。排查方式是在浏览器控制台查看图片请求的状态码如果是 403就用响应头确认是否被防盗链拦截然后去图床后台把当前域名加入白名单。6.5 导出的 Word 文档里图片排版混乱Pandoc 转换时图片默认的对齐方式、宽度控制可能和 Word 的默认样式冲突。可以在转换时指定一个参考文档reference docx 模板里面预置你想要的图片样式。这样 Pandoc 会把 Markdown 图片按模板格式排布整体会整齐很多。pandoc input.md -o output.docx --reference-docmy-reference.docx7. 结合我个人的使用习惯分享几个“非主流”但确实生效的偏方聊了这么多最后讲几个我私藏的小技巧。这些技巧不一定能写进官方文档但实测下来相当好用。第一个技巧给图片加“替代文本”不是可选项是必选项。写时描述尽量写得具体一些。虽然你平时预览时看不到它的作用但一旦图片加载失败读者看到的就是这段描述同时它也是无障碍阅读和 SEO 的重要一环。别图省事随手写个“img1”或者直接留空。第二个技巧截图的透明背景要留意。尤其在深色环境下编辑截图如果是白底贴到深色 Markdown 预览里会显得很突兀。用支持“窗口透明”截图的工具比如 Snipaste截图时保留透明背景图片插入文档后效果干净很多。第三个技巧给图片建立命名规范。我自己的规范是“日期-模块-序号”例如20250612-deploy-01.png。这样的好处是即使以后不用 Markdown改用 Notion、语雀等工具这个命名习惯依然通用文件管理不会乱。第四个技巧批量处理图片尺寸靠工具不靠手写 HTML。如果一篇文章里有二十张截图逐一写img width会很累。我通常用npx squoosh-cli或 ImageMagick 批量压缩和调整图片尺寸然后把 Markdown 里的图片统一用 CSS 控制展示宽度。这样图片文件体积小预览体验却不打折。以上这些内容都是我在各种 Markdown 项目中踩坑、填坑、再踩坑的经验总结。图片使用这件事看起来非常简单但真正规范起来涉及文件组织、路径管理、图床选型、导出链路等多个环节。每次觉得自己已经搞明白了就会在一个新场景下遇到新问题。我个人最大的体会是不要迷信某一种方案“万能”先弄清楚自己的使用场景——是个人笔记团队协作还是对外发布再针对性地选一种管理方式并坚持使用这样图片才会真的成为你写作路上的助力而不是麻烦制造机。