用 Typora 写 Markdown 最让人头疼的从来都不是语法而是图片。你花一上午截了 30 张图美滋滋地把文章粘贴到博客后台或者发给别人结果对方看到的是一串断点一样的叉号。问题就出在图片只存在于你电脑的某个文件夹里Markdown 文档里存的是本地路径换台设备、换个发布平台这个路径就彻底失效了。我最后选定并一直在用的方案是Typora PicGo Gitee码云搭建 Markdown 图床这套组合解决的就是图片有去无回的核心痛点而且完全免费、国内访问速度快、管理图片像管理代码一样方便。这篇文章会把整套方案的搭建过程、每个配置字段的实际作用、以及我踩过的那些教程里从来不写的坑全部拆开讲清楚。不管你是刚开始用 Typora 的新手还是写技术博客已经写到瓶颈的老手照着这套思路配置一遍后续写文章附图的体验会顺畅很多。1. 为什么图床方案要选 Gitee 而不是其他方式1.1 图片丢失的本质Markdown 里的图片路径是相对世界Markdown 文本本身不能包含图片它只能通过引用路径来展示图片。这个路径可以是本地绝对路径D:\笔记\截图\00.png、相对路径./images/00.png也可以是网络 URLhttps://xxx.com/00.png。前两种方式都依赖你当前的设备。本地绝对路径换一台电脑就找不到相对路径只要文件夹位置移动图片也全部失效。只有网络 URL 是稳定的——图片已经上传到了某个服务器上任何时候、任何设备打开这篇文章只要 URL 还在图片就能加载。图床干的事本质上是把图片从本地相对世界搬到网络绝对世界。当你在 Typora 里粘贴一张图片它能自动帮你完成备份到服务器 生成 URL 替换 Markdown 引用这一整套动作这就是我们常说的 Typora 图床功能。1.2 备选方案的实际体验对比我并不是一开始就用 Gitee早期试过很多方案各有各的坑简单做个对比供你参考方案成本访问速度稳定性主要缺点本地相对路径免费极快换设备即失效不能用于发布场景云厂商对象存储OSS/COS存储流量费快高需要实名认证和备案配置复杂公共免费图床免费不稳定低随时可能关闭或被墙不可控代码托管平台GitHub/Gitee免费国内一般较高仓库容量有限需要接受公开云厂商的对象存储确实是最正规的图床方案但如果你只是个人写博客、做笔记为了放几张截图就去研究和配置对象存储成本太高了光是域名备案那一关就能劝退大多数人。而代码托管平台建一个仓库专门放图片不上传代码只用它的静态文件访问能力这是性价比最高的选择。1.3 为什么是 Gitee 而非 GitHub很多老教程推荐 GitHub 图床GitHub 本身是好用的但它的 raw 文件访问地址对于国内网络环境来说速度并不理想。图片加载慢会直接影响文章阅读体验这不是换一个图床能解决的。Gitee 的仓库访问速度和 raw 文件直链访问速度在大多数情况下快得多而且同样支持通过 PicGo 插件自动上传。我一贯的选择原则是能用国内平台完成的事就不去绕更远的路径。Gitee 作为图床仓库配合 Typora 和 PicGo正好构成一条完全在国内网络环境下顺畅运行的链路。2. 在 Gitee 上建图床仓库容易留坑的几个决策点2.1 新建仓库的关键配置首先登录 Gitee进入新建仓库页面。仓库名强烈建议单独建一个不要混进你的代码仓库。比如叫image-hosting这只是示例你可以改成自己的一眼能看出用途后面维护也清楚。有两个选项需要特别留意第一个是是否用 README 初始化仓库。建议不要勾选直接创建一个空仓库。很多教程让你建仓库时顺手勾上 README这对代码仓库没问题但对图床仓库来说空仓库结构越简单越好后面 PicGo 插件往仓库里传图片时目录层级的判断会更直接也少了一些分支名相关的干扰因素。第二个是仓库可见性。这里我要提醒一个很多人不知道的细节Gitee 的私有仓库虽然可以上传图片但上传后生成的图片直链外部浏览器在无登录态的情况下是无法直接访问的。而图床链接恰恰需要第三方匿名访问所以图床仓库基本只能选公开。不少人在私有仓库里上传成功了图片却怎么也显示不出来排查半天才发现是卡在仓库可见性上。如果你担心图片隐私处理方式是把敏感内容打码或者不要把涉及个人隐私的图片放进图床仓库。图床仓库本身建议只放适合公开的内容。2.2 生成私人令牌截图保存的关键一步图床插件要把图片写入 Gitee 仓库需要凭证。这一步用的是私人令牌相当于为第三方工具单独签发的一张门禁卡。在 Gitee 页面右上角点头像进入个人设置找到私人令牌一栏点击生成新令牌。需要给它起个描述比如PicGo 图床上传使用方便以后在令牌列表里认出来。权限选择这里只需要勾选projects相关权限即可不需要全选。令牌权限最小化是安全习惯即使某个工具的令牌泄露了影响范围也能控制在项目管理这一层面。生成之后页面只会完整显示这一次把令牌复制到一个安全的地方保存好再关闭页面。注意私人令牌等同于一串账号凭证泄露了别人就能往你的仓库里传文件。不要把它贴进博客、不要提交到代码仓库也不要随手发给任何人。2.3 仓库建好之后先手动确认一件事仓库创建并设为公开后先手动生成一个 raw 链接测试一下。在仓库里随便上传一个测试图片文件点击这个文件在页面上找到原始数据或Raw入口复制对应 URL 在浏览器里打开如果能够在无登录状态下直接看到图片说明这个仓库可以当图床用了。这一步提前做比后面整套配置完再排查省事得多。3. Typora 与 PicGo 联动两个软件之间如何配合3.1 先安装 PicGo再装 Gitee 图床插件PicGo 是一个开源的图床上传工具它本身不提供服务器而是作为各种图床的上传中间人。Typora 负责检测图片PicGo 负责把它传到指定图床两个软件通过本地端口通信。PicGo 的安装很直白Windows 安装包装完直接运行macOS 拖到应用文件夹。打开后界面分成几个区块上传区、图床配置区、插件区和相册区。刚装好的 PicGo 默认支持若干图床但不支持 Gitee需要安装第三方插件。进入插件设置搜索关键词找到gitee-uploader这个插件并安装。这一步偶尔会失败多试几次或者重启 PicGo 再装。安装成功后左侧图床设置里会新增一个 Gitee 图床的配置入口。3.2 插件配置字段逐项说明进入 Gitee 图床配置页面你会看到这些字段配置字段作用填什么repo上传目标仓库格式是用户名/仓库名用户名是 Gitee 个人空间地址里的那个不是昵称branch上传到哪个分支新建仓库默认分支名一般是 master在这里准确填入token上传凭证之前生成的那串私人令牌path仓库内自定义目录比如填img/表示图片上传到仓库里 img 文件夹下留空则直接在根目录customUrl图片链接前缀留空时为默认 Gitee 地址如果自己挂了自定义域名可以填这个配置里最容易填错的是repo。很多人把博客用户名当成 Gitee 用户名传一张图报一堆 404 错误。记住这里的用户名是你 Gitee 个人主页 URL 里的那一段带仓库名一起填进去比如你的用户名/image-hosting。path字段建议不要留空尤其在图片较多的情况下。不设置的话所有图片直接铺在仓库根目录时间长了会非常杂乱。建议这一段按你自己的习惯规划比如按年份或文章名建个子目录前缀。3.3 处理完插件配置先在 PicGo 里试传一张这步非常关键。配置完成后先不要打开 Typora直接在 PicGo 的上传区复制一张剪贴板里的图片或者把一个本地图片文件拖进上传区看上传是否成功。如果 PicGo 自身上传失败问题大概率出在插件配置或网络环境跟 Typora 没关系。此时先看 PicGo 的提示信息再对照插件配置逐项检查repo漏了用户名、分支名填错、令牌没有权限这些都能在这个环节暴露出来。3.4 Typora 里指定上传服务和路径确认 PicGo 能独立上传后打开 Typora进入文件 → 偏好设置 → 图像。在图像插入相关设置里把图片的插入方式调整为上传图片下面的上传服务选择PicGo(app)然后在下方填入 PicGo 的安装路径。Windows 下是这个软件安装目录里的 exe 文件路径macOS 下是应用程序里 PicGo 的路径。Typora 偏好设置里还有几个跟图片相关的选项建议按你的写作习惯设置好插入图片时如果剪贴板是图片直接粘贴上传成功后会显示为网络图片如果文档里有历史遗留的本地图片可以在菜单的格式 → 图片里找到批量上传功能。配置完成后重启一下 Typora让设置生效。这套链路里 Typora 期望的是本机 PicGo 服务随时待命所以如果日常写作频繁建议把 PicGo 设为开机自启Typora 调用时不需要每次手动打开它。4. 完整验证上传链路从截图到 URL 的每一步4.1 用一张剪贴板截图做完整的端到端测试配置全部完成后做一次端到端验证。复制一张截图到剪贴板在 Typora 中直接粘贴观察图片是否自动变成了网络 URL。成功时有几个标志Typora 右下角会弹出图片上传成功的提示图片右键查看图片地址看到的是以https://gitee.com/...开头的一长串浏览器地址栏打开这个链接能独立看到图片。如果粘贴后 Typora 里还是显示本地文件路径说明上传服务没有生效需要回头检查 Typora 偏好设置里的上传服务是否选对如果显示的是 URL 但打不开则要看 PicGo 的成功日志和 Gitee 仓库是否真的有文件。4.2 生成的链接长什么样为什么是 raw 路径PicGo 插件成功上传后生成的链接格式大致是https://gitee.com/你的用户名/仓库名/raw/分支名/path/图片名.png注意路径里的raw这是 Gitee 对外提供原始文件的访问方式。raw地址返回的是纯图片内容浏览器可以直接渲染。还有一类地址是blob开头那是文件详情页面的链接加载的是一个带页面框架的网页不能直接当图片 URL 用。图床一定用 raw 链接。这个 URL 里也包含了你的用户名和仓库名。因为图床仓库是公开的拿到链接的人理论上也能看到仓库里其他图片文件所以前面才强调图床仓库不能放敏感内容。4.3 粘贴到博客和公众号的注意事项图床链接生成后把整篇 Markdown 粘贴到各个平台时还要注意目标平台的图片外链策略。大多数博客平台是支持外部图片直链的粘贴后不需要重新上传图片。少数渠道出于自身防盗链策略考虑会拦截外部图片或者需要在编辑器里手动替换这种情况属于平台限制不是你这套图床没搭好。如果哪次发出去的图片部分不显示可以先复制图片链接在浏览器里打开测试。浏览器能打开说明图床没问题要考虑是不是目标平台做外链限制。5. 最容易踩的坑链路不通时的完整排查思路5.1 现象一图片在 Typora 里显示但发布后变成叉号这是问的人最多的情况。先复制 Typora 里这张图片的地址如果地址还是本地路径说明根本没有触发上传重点检查 Typora 偏好设置里的上传服务选择。如果地址已经是https://gitee.com/...开头打开浏览器访问这个地址能打开则是目标平台拦截打不开则要查仓库可见性和 raw 路径是否正常。这条排查链路的顺序很重要先看 Typora 生成了什么再看浏览器能不能打开最后才轮到怀疑博客平台。很多人一上来就怀疑图床挂了其实问题往往出在最前面两步。5.2 现象二上传提示失败日志显示仓库相关错误PicGo 上传失败时在 PicGo 的日志文件或提示里会看到具体的状态码。仓库相关的报错一般集中在 404/401/403 这三个状态状态码常见原因处理方法404repo 里的用户名写错/仓库名不对分支名填错核对 Gitee 个人空间 URL 用户段核对仓库默认分支名401/403令牌不存在、未授权或没有对应权限重新生成令牌确保勾选了 projects 权限404 且仓库名无误path 路径开头多写了/或层级不对检查插件配置里的 path 是否和仓库内实际结构一致一个很容易被忽略的细节Gitee 仓库是大小写敏感的仓库名、分支名、目录名的大小写不一致都会导致上传后生成一个 404 链接。很多仓库名用的下划线、中划线会在复制粘贴时被编辑器自动转换填配置时尽量手动输入不要复制。5.3 现象三Typora 提示上传服务启动失败这种情况通常是 PicGo 没有被正确识别。先确认 PicGo 当前是打开状态再检查 Typora 填写的 PicGo 路径是否正确。如果路径没问题关闭两个软件后重开一次大多数情况下服务就能连上。在 macOS 上如果仍报连接失败可以尝试在 Typora 偏好设置中重新选择一下应用路径这个偶发情况和系统权限管理方式有关重选一次就好。5.4 现象四图片上传成功但部分图片互相覆盖另一个常见问题是图片重名。很多截图工具生成的文件名很随意比如123.png、截图.png这类通用名。如果你连续插入多张同名图片那么上传到同一个仓库目录时可能会互相覆盖最终仓库里只有一个文件多个链接指向同一个图。解决思路是在 PicGo 设置里开启文件重命名或者把插件配置里的path调整为带日期或文章名的子目录结构让每篇文章的图片落在各自独立的目录下规避重名覆盖的风险。5.5 一堆小经验别让这些绕弯子的问题消耗耐心PicGo 插件安装偶尔会因为各种原因失败本地网络、node 环境缓存都有可能。遇到安装不上的情况建议先卸载再重装仍然不行就重启 PicGo 再试不用过度焦虑。还有一个扎心的规律要提前说免费图床方案永远处于一个正在被平台调整的动态环境里。Gitee 的 raw 链接策略、仓库规则、PicGo 插件的适配性都可能随时间变化。你现在照着文章配好没问题不代表半年后零维护。关键是自己要掌握排查链路而不是一直依赖现成的教程。6. 让图床方案更趁手的几个进阶思路6.1 规划目录结构和管理仓库如果写的内容类型比较多建议在 Gitee 图床仓库里规划一套固定目录前缀配合 PicGo 插件里的path使用。比如按写作领域分notes/、blog/、work/或者按年份分2025/。上传时插件会自动创建目录不需要手动去 Gitee 网页端建文件夹。仓库里的图片只增不减时间久了文件会越来越乱需要在网页端定期整理。不定期地打开 Gitee 仓库文件列表把已经没有在用的图片目录批量删除或者移动到备份文件夹里。6.2 图片体积控制更实用做知识库截图或技术文章配图时如果图片体积过大仓库容量消耗会很快。建议注意截图源头的体积控制不需要保留高清大图的截图可以用图片处理工具做压缩。高频写作场景下尽量使用 PNG 或 JPG 压缩格式不要动不动截一张几 MB 的高清图传上去。这一步虽然小但长期下来对仓库可用空间影响很明显。6.3 这套方案的适用边界要心里有数我把话说透Typora PicGo Gitee 这套组合适合个人笔记、博客配图、技术文章但不适合大流量访问场景也不适合存放重要隐私图片。Gitee 仓库本质上是项目管理工具并不是专业 CDN因此面临高并发访问时会比较吃力链路不稳定也需要留意。正经做产品级图文服务该付费上对象存储就上对象存储这个是两码事。6.4 换个角度如果某天平台不再友好图床方案最大的风险在于单一依赖某一个平台。为了给这种风险上一个保险我自己的做法是写作源文件里除了通过图床 URL 引用图片外本地还是保留一份原始图片副本。哪怕有一天图床仓库出现了问题本地图片依然不会丢失修改一下前缀或重新上传即可恢复。这套工作流有多顺取决于你平时有没有保存原图这个习惯能坚持做到以后的迁移成本就低很多。最后分享一点实操领悟。配置这套链路时一定要按流程顺序来不要跳步先把仓库和令牌准备好再单独让 PicGo 跑通最后才接 Typora。很多人配不好都是因为一上来就在 Typora 里点上传结果出了问题不知道是仓库、插件还是编辑器的问题。按顺序穿好每一节任何一个环节出故障你都能第一时间定位到那个具体的组件。我自己就是这么一步步试出来的把这套顺序记在脑子里比你反复翻教程管用得多。