把 Markdown 文档推上 GitHub结果一把本地图片变成小方框这种事我身边写博客、维护开源项目的人几乎都遇到过。本地图片和 GitHub 在线图片之间差的不只是一次上传而是一整套路径认知本文要解决的问题就是让 Markdown 里的本地图片一键变成能稳定访问的 GitHub 在线图片。我会从原理讲到可以复制运行的脚本覆盖适合把文档托管在 GitHub、又不想依赖第三方图床的人也能帮只处理少量图片的新手避开最常见的坑。1. 图片裂开不怪 Markdown要怪「本地」两个字1.1 预览器看到的路径和 GitHub 看到的路径从来不是同一套你在本地用 Typora、VS Code 或任意 Markdown 编辑器写时渲染器会怎么做它拿到一个相对路径./images/architecture.png然后基于当前 Markdown 文件所在的目录去找这个文件。你的磁盘上确实有这个文件所以预览完美无缺。问题出在 GitHub 端。README 也好、仓库里的.md文档也好最终都是作为网页渲染的GitHub 服务器不可能到你的电脑上找./images/architecture.png。如果图片没有和 Markdown 文件一起提交到同一个仓库或者你把这份文档贴到了 Gist、第三方知识库、某个不支持仓库相对路径的渲染平台这个相对路径就废了。图片没有跟着文档走裂图是必然结果。有人会提出反驳我的 README 里写图片也在仓库的images/目录下GitHub 上显示得好好的。对这是成立的因为 GitHub 对「仓库中已提交文件的相对路径」能做渲染。但请注意这种渲染依赖图片和文档处在同一个仓库、同一次提交上下文中。一旦文档被复制到别处、导入其他工具、或者以单文件形式发给别人相对路径立刻失去意义。1.2 能被任何平台稳定渲染的图片必须有一个绝对可访问的 URL仔细拆一下 Markdown 图片引用其实只有两类引用形式本地编辑器预览GitHub 仓库页面Gist/第三方渲染发给别人且图片只在本地正常裂图裂图裂图且图片已提交到同一仓库取决于工作目录正常多数裂图多数裂图正常正常正常正常所以结论很直接只要图片的地址是一个完整的在线 URL它在任何地方都能渲染。GitHub 在线图片本质上是「把图片文件放进一个公开仓库并获得一个指向该文件的公开 URL」。这个 URL 可以直接是 GitHub 的 raw 地址也可以是 jsdelivr 这类公共 CDN 转发地址。1.3 blob 页面不是图片地址raw 才是很多人把 GitHub 仓库里打开图片文件后浏览器地址栏那段 URL 复制出来用比如https://github.com/owner/repo/blob/main/pics/a.png这段 URL 打开后确实是一张图片但它本质是一个网页服务器中间还套了 GitHub 的页面框架和其他内容。你在 Markdown 里引用这种地址编辑器大概率会尝试拉取整个 HTML 而不是图片二进制表现就是加载慢、渲染异常。GitHub 为每个仓库文件提供了 raw 端点https://raw.githubusercontent.com/owner/repo/main/pics/a.png这个地址返回的就是文件原始字节浏览器拿去能直接渲染Markdown 编辑器也能正确处理。这是整个转换方案里最核心的理念不是随便找一个 GitHub 链接就完事而是要拿到文件本身的 raw URL。2. 一键转换的整体链路扫描、上传、替换缺一不可2.1 脚本在设计上其实就三步先别急着写代码把整件事拆成链路图。任何一个 Markdown 文件从「本地图片」变成「GitHub 在线图片」技术上绕不开这三步扫描 Markdown 内容把所有图片引用抓出来筛出那些指向本地文件的相对路径把图片文件通过 GitHub API 上传到一个公开仓库里得到远程文件路径用上传后生成的 raw 地址或 CDN 地址替换 Markdown 里原来的本地路径再把文件写回去。这三步听起来简单真正落地时每一步都有边界情况。第 1 步要处理路径里有空格、中文、括号的文件第 2 步要处理 GitHub 仓库默认分支是main还是master、远端是否已经有同名文件第 3 步要小心替换时不要把已经在线的外链图片也重复处理。2.2 为什么我用 GitHub 仓库当图床而不是第三方图床做图片托管有几条主流路线GitHub 仓库、七牛/阿里云 OSS/腾讯云 COS 等对象存储、还有专门做图床的网站。要回答「为什么选 GitHub」得看清楚自己的真实场景。对比项GitHub 仓库做图床专业对象存储/图床成本免费流量费用随用量增长图片提交历史有完整 Git 记录一般没有图片管理