Markdown与HTML中引用上传文件直链的规范与懒加载优化

把上传后的文件放进博客或说明文档，核心目标是让图片能正常显示、附件能顺利打开，并让首屏之外的图片实现按需加载。相比一开始就给所有图片强制加上懒加载，先确认地址指向真正的文件内容，再根据位置选择 Markdown 或 HTML 写法，最后检查发布页面的实际表现，是更稳妥的操作路径。

下面以一张已上传的流程图和一份 PDF 文档为例，站点内路径分别为 https://img.ipython.cn/uploads/flow.webp 和 /uploads/readme.pdf。示例代码中的路径需替换为你自己文件的实际地址；本文聚焦于纯浏览器页面和文档渲染规则，不涉及特定系统版本的软件安装。

在开发者工具中检查资源返回类型

1. 先验证地址返回的是图片或附件

在浏览器新标签页中直接打开文件地址。对于流程图，页面应直接呈现图片内容；对于 PDF，应直接展示文件或触发下载，而不是先跳出分享列表、提取码输入页或登录表单。能打开带有预览功能的分享页面，并不代表该地址适合直接放入代码的图片标签中。

还要考虑读者身份权限。你自己登录后能看见的资源，未登录的读者未必能访问。需要公开展示的非敏感资料，应使用允许公开访问的发布地址；私密资料则应保留原有的鉴权机制，不应仅仅为了嵌入方便就取消保护。

在浏览器开发者工具的【网络】面板中，刷新页面后选中该资源，检查状态码、响应内容和 Content-Type。例如 WebP 图片应有对应的图片媒体类型；如果返回的是 HTML 错误页，即使地址末尾看起来像图片后缀，也要先修复访问地址。

若使用带有效期的签名地址，必须连同参数完整保留。临时地址用于长期文档时，需要有后续更新方案，不能删掉查询参数后假定链接仍能永久使用。

2. 图片用图片语法，普通附件用链接

在 Markdown 中，图片描述写在方括号内，图片地址写在圆括号内：

对于 PDF 等附件，使用普通链接语法：

[打开使用说明PDF](/uploads/readme.pdf)

两者的区别就在开头的感叹号。如果把 PDF 写成图片语法，浏览器不会自动把整份文档当作一张图片展示；若需要嵌入阅读器，应另行确认发布平台支持的组件。

同样的图片若使用 HTML 编写，可以这样写。这里假设原图实际尺寸为 1200×675，替换图片时也要换成它自己的真实尺寸：

alt 用于说明图片内容，width 和 height 提供尺寸比例，样式则让图片在较窄的内容区按比例缩放。普通附件对应的是链接标签：

<a href="/uploads/readme.pdf">打开使用说明PDF</a>

PDF 最终是在浏览器中预览还是直接下载，还受浏览器能力和服务端 Content-Disposition 等响应信息影响，不能仅凭链接文字保证某种特定的打开方式。

Markdown中图片与附件链接的语法区别

本文的 /uploads/ 写法表示当前站点根目录下的资源。若 Markdown 要在其他域名或离线阅读器中使用，应换成在那里也能解析的实际地址，不能假设站点根路径到处通用。

3. 给正文后段图片加懒加载，首屏图先保留正常加载

当流程图位于文章后段、初次打开页面时看不到，可以在 HTML 图片标签上添加 loading="lazy"：

浏览器可根据图片与可视区域的距离推迟请求，直到读者接近图片位置时才加载。不要把它理解为“滚到某一像素才必须发请求”，具体的提前量由浏览器决定。

如果这张图就是首屏的重要效果图，保留前一节没有 loading="lazy" 的写法即可。首屏内容本来就需要尽快出现，强行延后它反而可能影响阅读体验。

尺寸属性仍然要保留。图片还没下载时，页面可以利用宽高比例提前安排空间，减少图片出现后把下面文字往下推的情况。懒加载也不能替代合理的图片尺寸和压缩：如果原文件过大，真正加载时仍要付出传输成本。

标准 CommonMark 图片语法没有通用的 loading 属性写法。当平台允许原生 HTML 时，可以使用上述标签；若平台过滤 HTML 或属性，应使用它的图片设置、主题模板或受支持插件。不要随意在 Markdown 图片后加一段自创属性，并认定每个阅读器都会识别。

4. 在最终页面检查，而不只看编辑器预览

保存文档后，打开实际生成的预览页，确认图片描述、显示比例和 PDF 链接都符合预期。随后检查最终 HTML 中的图片标签，看看 loading、width、height 是否被渲染器保留；有些编辑器的预览效果与发布页面使用的规则并不相同。

在 Windows 电脑的 Chrome 浏览器中打开开发者工具，切到【网络】面板，再刷新页面。按图片类型或文件名找到流程图请求，观察首屏是否需要它，再向下滚动，确认后段图片在接近可视区域后能够显示。

验证时要考虑缓存和浏览器的提前加载策略。某张懒加载图片在滚到它之前已开始请求，并不能单独证明设置无效；应结合它的位置、最终属性和网络记录一起判断。若出现 404、403 或返回登录页面，先处理地址和权限问题，再讨论加载优化。

最后再打开一次 PDF，确认内容正确。首屏图及时出现、后段图按需加载、附件链接确实可用，这三项都成立，才算把上传文件正确接入了文档。

4. 在最终页面检查，而不只看编辑器预览