Typora结合Gitee免费图床，彻底解决Markdown图片本地路径问题-北京尧图网络

如果你写过几篇带图的Markdown笔记大概率遇到过这种场景换台电脑打开之前的文档整排图片变成了灰色裂图标把笔记发给朋友对方看到的是满屏路径或者某天整理文件夹手一抖图片目录没了整篇文章就成了文字骨架。本地图片这条路看着省事实际上把Markdown的便携性和稳定性砍掉了一大半。这篇文章想聊的就是用Typora搭配gitee图床构建一套稳定、免费、能自动上传的图片托管方案让Markdown里的图片彻底告别本地路径。这套方案我自己跑了快两年笔记从几十篇长到了七八百篇图片文件上千张中间踩过不少坑也总结了一些排查思路。下面会先从本地图片的问题讲起再一步步把gitee图床、PicGo、Typora三个环节串起来最后附上完整的高频故障排查链路希望能帮同样被本地图片折腾过的人一次搞定。1. 本地图片到底坑在哪Markdown写作的隐性炸弹很多人刚开始用Markdown时都是直接在Typora里拖一张图进来看到![](assets/xxx.png)这样的代码就满足了。这个阶段不会遇到任何问题直到你开始换设备、换目录、发布文章或者把文档发给别人问题才会集中爆发。1.1 一张消失的图片引发的连锁反应先还原一个我实际遇到的场景。某天我在公司电脑上写了一篇带截图的内部技术方案里面插了大概二十张图片路径都是相对路径./images/。晚上回家用笔记本打开同一个仓库图片全部裂了。原因很简单我回家后拉取的代码里图片文件是放在docs/images/下但Markdown里写的是images/xxx.png根目录变了路径自然就失效了。这就是本地图片的第一个问题Markdown里的图片引用本质上是一个相对路径依赖图片文件与文档文件之间的物理位置关系。一旦这个关系被打破——文件夹移动、仓库结构改变、换一台电脑、不同系统对路径分隔符的解析差异——图片就会立刻失效。你不用管图片“在不在”只要路径对不上它就等于不存在。更隐蔽的坑是文件名编码问题。Windows上如果你用中文或带空格的文件名Typora能正常显示但文档一旦发布到Linux服务器或者交给Mac用户打开非常容易出现编码解析失败。我见过最离谱的一次是把笔记压缩成zip发给同事对方解压后所有图片都带%20转义因为压缩工具在打包时把空格替换成了转义字符。1.2 图床的本质把相对路径变成绝对URL理解了上面的坑解决方案的思路就很清楚了只要图片不依赖本地文件路径而是通过一个网络URL来引用那么无论文档在哪个设备、哪个目录、发给谁只要对方能联网图片就能显示。这就是图床方案的核心逻辑。所谓图床其实就是一个“专门存放图片的远程存储服务”它把图片放在服务器上返回给你一个固定的HTTP地址。Markdown里写的不再是assets/xxx.png而是https://gitee.com/yourname/blog-images/raw/master/img/xxx.png。这个URL是绝对的、唯一的、可公开访问的和你的本地目录结构完全无关。这个转化的意义不只是“图片不会裂”。它还会带来几个额外收益文章体积变小本地图片动辄几MB写进版本库会让git仓库迅速膨胀每次克隆都痛苦。图床方案下仓库里只有文字图片全在云端。文档可移植性大幅提升同一份Markdown可以直接扔进博客、知识库、公众号编辑器不需要单独打包图片目录。同步冲突减少用坚果云、OneDrive等工具同步笔记时本地图片经常因为同步延迟导致文件锁冲突图床方案没有这个问题。当然图床也有代价——依赖第三方服务的稳定性和外链策略。所以图床服务的选择就显得格外关键。1.3 图床方案横评为什么gitee值得专门写一篇市面上的免费图床不少但真正适合中文用户日常写作的其实不多。我简单排过一遍GitHub图床最主流raw域名全球可用配合jsDelivr加速CDN免费。但国内直接访问github raw地址时好时坏而且仓库如果不公开外链基本没法用。阿里云OSS / 腾讯云COS稳定、快但收费虽然几块钱一个月但总要绑卡还要配置防盗链和CDN对于只是写写笔记的人来说过重。sm.ms / 路过图床等公共图床匿名上传方便但公共图床有删除风险、容量限制图片存别人服务器上人家随时可能关停或清理做临时分享还行长期当笔记图床不踏实。gitee图床码云在国内访问速度非常快个人仓库容量1GB单文件上限100MB对写文档放截图完全够用而且支持私人令牌配合PicGo插件能实现全自动上传。有人会问gitee不是代码托管平台吗拿来放图片会不会被限流坦白说gitee并不是专业的对象存储但它有raw文件直链允许公开仓库下的文件通过URL访问。只要你的图片总量控制在几百MB以内、不是拿来刷流量日常写作场景完全能hold住。我用了两年目前还没有被限制过。所以这篇文章就围绕gitee图床来写。接下来从最基础的仓库和令牌准备开始。2. 搭建前的准备仓库、令牌和工具链选型很多教程一上来就让你装PicGo结果配到一半发现token没生成、仓库分支名不对来回折腾。这里我把准备工作单独拆出来每一样都讲清楚为什么这么做。2.1 gitee账号与公开仓库的配置细节第一步是注册一个gitee账号这个没什么好说的手机号加密码就行。注册完之后进入“新建仓库”页面有几个字段会直接影响后续图床是否可用需要认真填仓库名称建议用blog-images或notes-images这种一眼能看懂的名字不要用test、temp这种太随意的。路径gitee会自动根据仓库名生成路径一般保持一致就行。私有还是公开这里非常关键。图床仓库必须选择“公开”否则图片URL无法被外部直接访问。我见过很多人把仓库设为私有然后老问为什么图片外链打不开。私有仓库的raw链接需要登录鉴权Typora/PicGo上传后产生的链接是给浏览器、博客、知识库用的不可能每次访问都登录。初始化仓库建议勾选“初始化仓库”并添加一个.gitignore文件。仓库创建好之后会有一个默认分支gitee默认是master少数新仓库可能是main。这个分支名后面配置PicGo时要严格保持一致很多404错误就出在这。开源许可证选什么gitee在创建公开仓库时会要求选择一个开源许可证License。如果你是拿gitee当图床既不打算开源代码也不需要别人二次分发选最宽松的MIT即可。它字数最少约束最少纯属是为了满足平台对公开仓库的形式要求。如果你有代码在里面再根据实际情况选。创建完成后你会在仓库首页看到“HTTPS”和“SSH”两个克隆地址。这里注意一个容易混淆的点图床用到的raw链接格式不是仓库地址而是https://gitee.com/用户名/仓库名/raw/分支名/文件路径。这个链接需要在PicGo里手动拼接下面会详细说。2.2 私人令牌Token怎么生成才算安全PicGo要上传文件到gitee仓库不可能每次用用户名密码登录它需要一把“钥匙”——个人访问令牌Private Token。生成路径是gitee右上角头像 - 设置 - 安全设置 - 私人令牌 - 生成新令牌。生成时最关键的是权限范围选择。gitee的令牌权限有很多项但对图床来说只需要勾选projects就够了。这个权限允许通过API操作仓库包括创建文件、修改文件。其他的权限一律不勾权限越少越安全。提交后会生成一串形如a1b2c3d4e5f67890abcdef的随机字符串。这个令牌只在创建时显示一次刷新页面就再也看不到了务必立刻复制到本地临时文件里。令牌相当于你账号的一把副钥匙泄露给别人就能直接改你仓库里的内容。所以日常使用中要注意不要把令牌写进博客文章、截图、issues里。PicGo配置会明文保存token如果电脑多人共用建议离开时锁定屏幕。如果怀疑泄露去gitee后台随时撤销重新生成成本很低。2.3 上传链路选型PicGo gitee-uploader插件图片从Typora到gitee中间需要一个脚手架目前最顺手的工具是PicGo。它是一款开源免费的桌面图片上传工具支持Windows和macOS能和Typora无缝联动。PicGo的核心能力是监听剪贴板图片、调用上传插件、把返回的Markdown图片链接写回剪贴板或发送给Typora。选择PicGo而不直接用Typora内置的“自定义命令”是因为PicGo有图形界面、能看日志、能批量上传出错时排查起来直观很多。Typora内置的自定义命令虽然轻量但输出解析很麻烦不适合新手。PicGo的gitee支持并不是内置的需要在它的插件市场安装一个第三方插件。目前比较常用的是gitee-uploader插件作者写的是Mr. H等不同版本维护者略有差异。安装方式打开PicGo - 插件设置 - 搜索gitee-uploader- 安装。安装完后在PicGo左侧栏会出现一个“Gitee图床”的配置项。到这里准备工作就绪。接下来进入正式配置环节我会按“PicGo配置 - Typora配置 - 首次上传实测”的顺序一步步走。3. 手把手配置三步让Typora自动上传图片这一节的目标很简单在Typora里粘贴一张截图图片自动上传到giteeMarkdown里自动出现一个网络图片链接。全程不需要手动复制、打开网页、传文件。3.1 PicGo的安装与gitee插件配置先去PicGo官网下载对应系统的安装包安装完成后打开。macOS用户注意首次打开可能会被系统安全策略拦截需要在“系统设置 - 隐私与安全性”里允许从“App Store和被认可的开发者”打开这一步是常见的卡壳点。打开PicGo后进入“图床设置”里的Gitee图床配置页你会看到四个关键输入框我直接给出对照表配置项填写内容说明repo你的用户名/仓库名例如zhangsan/blog-images必须和gitee仓库路径完全一致branchmaster以创建仓库时的默认分支为准别用main硬套token你的私人令牌粘贴刚才生成的令牌pathimg图片在仓库里的存储目录没有会自动创建可以按需改成images、assets/2025等customUrlhttps://gitee.com/你的用户名/仓库名/raw/master这是最终生成链接的前缀后面会自动拼上路径和文件名关于customUrl我见过很多人填错。它不是仓库首页地址而是“raw文件直链”的根地址。举个例子你的仓库是zhangsan/blog-images分支是master那么一张位于img/2025/01.png的图片最终访问地址就是https://gitee.com/zhangsan/blog-images/raw/master/img/2025/01.png所以customUrl应该填https://gitee.com/zhangsan/blog-images/raw/master最后不要带/。如果你填成了https://gitee.com/zhangsan/blog-images生成出来的链接会变成https://gitee.com/zhangsan/blog-images/img/2025/01.png这个地址不是raw直链在浏览器里打开通常只会跳到仓库文件页面无法被Typora和博客正常加载。配置完这四个字段先不要急着关窗口去“PicGo设置”里建议开启“时间戳重命名”。开启后上传的图片会自动命名为类似20250101123456_abcd123.png的格式好处有两个一是避免重复文件名互相覆盖二是英文数字文件名在URL里兼容性最好不会出现中文被转义导致显示异常的问题。3.2 Typora侧的上传服务配置打开Typora进入“文件 - 偏好设置 - 图像”这一步是打通编辑器和PicGo的关键。设置如下插入图片时选择“上传图片”。这样你从剪贴板粘贴截图Typora会直接把图片交给PicGo上传而不是先存到本地。上传服务选择“PicGo(app)”。PicGo路径macOS填入/Applications/PicGo.appWindows填入C:\Users\你的用户名\AppData\Roaming\PicGo\PicGo.exe这类安装路径。点击“验证图片上传选项”Typora会尝试调起PicGo如果配置正确会弹出一个上传成功提示。这里有一个细节Typora和PicGo的通信是基于本地端口的所以使用前要确保PicGo在后台运行。如果你完全退出PicGoTypora会提示“上传失败”。很多第一次上手的人以为Typora会自动拉起PicGo实际上并不会它只会尝试连接。另外如果你希望所有历史图片也能一键上传Typora还有一个“上传所有本地图片”的功能这个我放到后面批量迁移部分详细讲。3.3 首次上传实测从剪贴板粘贴到浏览器验证配置完成后来一次完整的上传演练。按CtrlShiftV或截图工具直接复制到剪贴板在Typora文档里按CtrlV粘贴一张截图。正常情况下Typora会短暂显示“正在上传”然后图片消失在文档里的瞬间代码区域会出现一行如下格式的Markdown![image](https://gitee.com/zhangsan/blog-images/raw/master/img/20250101123456_abcd123.png)然后在文档里应该能看到图片正常渲染。到这一步核心流程已经通了。但我强烈建议多做一步验证把上面这个链接复制到浏览器无痕窗口里打开。为什么要用无痕窗口因为普通浏览器可能带gitee的登录cookie即使仓库是公开的有cookie和没cookie的访问结果有时不一样。无痕窗口能模拟一个没有任何登录状态的陌生访客这也是博客读者看到的真实效果。如果无痕窗口能正常显示图片恭喜你本地图片的问题彻底解决了。如果打不开别急大概率是分支名或URL拼接问题直接跳到下一章排查。4. 真实使用中的高频故障从403到404的完整排查链路图床方案最怕的就是“上传成功但图片打不开”或者“直接上传失败”。这一章我把常见问题按现象归归类每个都给出定位思路和解决方案。排查的核心原则是先看PicGo的日志输出再点开生成的链接看返回内容最后检查配置项。4.1 第一类问题上传成功但图片不显示这类问题最迷惑人PicGo显示上传完成Typora里图片缩略图也有但浏览器或手机打开后就是不显示。现象一浏览器打开返回403 Forbidden403通常是权限或防盗链问题。gitee的raw服务对某些外部Referer场景有限制。解决思路是先在PicGo的customUrl里确认拼的是/raw/master/而不是/raw/main/或仓库主页路径。如果链接没问题还报403试试在链接末尾加参数?rawtrue即https://gitee.com/zhangsan/blog-images/raw/master/img/xxx.png?rawtrue有些版本对带查询参数的URL放行更宽松。另外如果你项目里有自定义域名映射或开启了gitee pages也可能影响直链。图床场景建议不要动这些高级配置。现象二返回404 Not Found404排在第一位的原因是分支名写错。我在排查过的大量案例里至少一半是PicGo里填了默认分支master但实际仓库分支是main。gitee新建仓库的默认分支可能因为你选择模板不同而不同一定要去仓库页面左上角确认当前分支名。第二个原因是URL里的路径和实际文件路径不匹配。比如PicGo里path填了img上传后仓库里确实建了img文件夹但你的customUrl里手滑多写了一层images结果变成/images/img/xxx.png自然找不到。第三个原因是文件名编码问题。如果图片名是中文gitee生成的URL可能是百分号编码Typora渲染没问题但某些博客系统解析会失败。这种情况下最好的解决方式是直接开启PicGo的“时间戳重命名”一劳永逸。现象三Typora正常显示但网页端或同事打开时图片裂了这种情况通常是Typora本地缓存了图片而实际链接已经失效。Typora有时会把已成功上传的网络图片继续缓存成本地缩略图视觉上“看起来正常”但你换台设备打开同一个文档就露馅。排查方法很简单在Typora文档中点一下图片看状态栏显示的是本地路径还是URL。如果是本地路径说明你这张图并没有真正走图床可能是在配置完成之前就已经插入的旧图。处理方式是把图片删掉重新粘贴一次或者用后面提到的“上传所有本地图片”功能手动处理。4.2 第二类问题上传失败或PicGo报错先看PicGo主界面的“上传区”和“相册区”有没有显示失败项再点开PicGo的日志窗口一般在窗口下方或右键菜单里。日志是排查的核心依据常见报错有报错一HTTP 400 - Invalid token这是token没填对或者token复制的时候带了空格、换行符。另外token也会过期或被撤销去gitee后台重新生成一个替换即可。报错二HTTP 422 - Invalid value for branch分支名错误。去仓库确认是master还是main改PicGo配置后重新试。报错三Connection refused或Timeout这个报错通常不是gitee的问题而是PicGo或网络本身的问题。检查系统代理设置、防火墙是否拦截了PicGo以及是否能正常访问gitee。如果你在网络环境里访问gitee都不稳定那图床肯定也不稳定。报错四Typora提示“上传失败”但PicGo日志为空这种大多是端口通信问题。Typora通过固定端口默认36677和PicGo通信如果PicGo被其他工具占用了端口或者你同时开了多个PicGo实例就会出现连不上。重启PicGo或者在PicGo设置里把端口改成一个空闲端口再在Typora里重新验证一下。4.3 第三类问题Typora本地预览正常发布到博客后挂了很多人用Typora写完文章会复制到博客后台。如果图片走的是图床理论上发布后应该正常显示。但实际会出现“本地ok发布后裂图”的情况常见原因有三个一是博客编辑器把Markdown里的URL转义了。有些博客系统会自动把、%等字符转义导致图片链接变形。解决方式是在博客后台使用Markdown原始编辑器或者关闭自动修正。二是gitee仓库被设成了私有。如果你在后续维护中发现仓库被误设为私有或者gitee规则调整别人就访问不了。图床仓库务必保持公开。三是图片触发了防盗链机制。有些博客站会设置跳转或保护导致直接外链gitee图片时被拦截。这种情况可以尝试在图片链接加上?rawtrue或者考虑把仓库图片同步到一个更开放的CDN上。如果你用的博客系统支持自定义字段还可以在主题里给图片链接统一添加一个referrerpolicyno-referrer属性这能绕过绝大多数防盗链限制。但这个偏前端工程师操作普通用户先不用管。5. 进阶玩法与边界批量迁移、路径规整和风险控制主流程跑通之后接下来要解决的是“历史文章怎么办”和“这个方案能用多久”的问题。这一章的内容全是实战中沉淀下来的操作习惯不是官方文档会告诉你的。5.1 把历史文章里的本地图片批量云化如果你和我一样已经积累了几百篇带本地图片的旧笔记不要慌Typora自带批量处理能力。操作路径打开一篇含本地图片的文档在菜单栏选择“格式 - 图像 - 上传所有本地图片”。Typora会把文档里所有本地相对路径的图片逐个调用PicGo上传然后自动把Markdown里的引用替换为网络URL。一次一篇效率也不错。如果你有几十上百篇文章可以写个脚本批量遍历但需要对Typora的自动替换逻辑足够熟悉个人建议在批量执行前先备份整个笔记目录。这里有一个重要的前置要求要上传的图片必须在本地存在且文件路径和时间戳要正常。如果你曾经移动过笔记目录部分图片已经丢失Typora会跳过并报错。碰到这种情况只能先补回图片文件再上传。5.2 图片命名、压缩与目录结构的最佳实践图床方案中图片的命名和目录规划直接决定你后期维护的体验。我踩过最大的坑是早期用中文文件名上传到gitee后一部分平台能访问一部分平台解析失败。后来强制改为以下规则文件名使用日期_随机数格式例如20250101_8921.png。目录名按年份或月份分例如img/2025/01/。这样一年后想看某个月的图能快速定位。文件格式截图用PNG照片用JPEG图标或简单图形用WebP但要注意部分老系统不支持WebP保守起见还是PNG/JPEG。文件大小尽量控制在500KB以内。gitee免费仓库总共1GB单文件如果太大一张图就能吃几十MB太浪费。截图的话可以用Typora自带压缩图片功能或者用工具批量压缩后再上传。这些规则虽然看起来有点强迫症但当你半年后要找某张图时就会发现结构化命名比一坨随机文件名强太多。5.3 免费图床的边界哪些图千万别放以及怎么兜底必须说实话gitee图床是“够用但非完美”的方案。它的本质是一个代码托管平台不是专业对象存储。因此在长期使用中要知道它的边界才不会在关键时刻翻车。不要放的图片身份证、合同、内部系统截图等敏感内容。虽然公开仓库只有你能上传但图床链接一旦泄露任何人都能访问。涉及隐私的图片请老老实实放本地或加密盘。同理如果你只是想在私密笔记里放图也别依赖公开链接。容量规划gitee免费用户单个仓库容量1GB五个以内私有仓库等等限制。对纯文字笔记来说1GB大概能放三四千张压缩后的截图。一旦接近上限要么压缩图片要么把老图片下线清理要么换付费方案。建议每季度看一下仓库体积心里有数。兜底策略图床不是银弹重要文章里的图片建议定期把markdown 图片URL清单备份到本地。其实备份不麻烦因为图片都在同一个仓库里你可以用git clone把图片仓库拉回本地。这样即使gitee哪天调整规则你手里的图片文件也不会丢随时可以迁移到其他图床。多图床冗余如果你是对稳定性要求很高的人可以在PicGo里同时配置多个图床插件比如gitee 阿里云OSS上传时手动选择。日常用免费的重要文章用付费的互备互援。另外如果你把Typora和Obsidian配合使用建议Obsidian里也保持同样的URL引用方式不要混用本地相对路径和网络URL。Obsidian的附件同步和Typora不同一旦两种路径混在一篇文章里后期维护会非常头疼。我个人在实际使用中还有一个习惯每次手动上传图片后顺手在浏览器地址栏敲一下链接确认返回的是图片而不是登录页。这个动作每次只花三秒钟但能避免很多“感觉上传了其实没上传”的假象。毕竟本地图片的坑我们已经踩够了图床方案就是为了彻底填上这些坑每一步都验证到位后面的写作才能真的安心。

Typora结合Gitee免费图床，彻底解决Markdown图片本地路径问题

相关推荐

AI辅助编码实战：5个案例拆解如何真正提升开发效率

AI辅助写作如何降低检测率？9款工具与一套控率流程

eNSP校园网实战：三层架构、VLAN、DHCP、OSPF与NAT配置全解析

更多资讯

冷热电三联供容量配置：基于多目标粒子群算法的Pareto优化实践

微信小程序+Flask+MySQL打造智能停车场计费车位系统详解

codex-register 生产部署指南：Docker Compose、数据持久化与数据库备份一次讲清

忘记Windows密码？免费BIOS级U盘工具重置SAM数据库

PowerEdge R7515单路EPYC服务器：Debian 12.5与Mellanox 25G网卡部署全记录

COMSOL多孔吸声JCA模型仿真：参数设置与多层结构应用

今日更新

Agent Skills 完全指南：原理、写法、安装与实战避坑

Agent Skills 实战：从 Genkit 定义到 GKE 部署与排查

Agent Skills 实战：从设计到调试的完整指南

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？