Typora + PicGo + Gitee 搭建免费 Markdown 图床，让配图永不失效

用 Typora 写 Markdown 最让人头疼的从来都不是语法，而是图片。你花一上午截了 30 张图，美滋滋地把文章粘贴到博客后台或者发给别人，结果对方看到的是一串断点一样的叉号。问题就出在图片只存在于你电脑的某个文件夹里，Markdown 文档里存的是本地路径，换台设备、换个发布平台，这个路径就彻底失效了。

我最后选定并一直在用的方案是Typora + PicGo + Gitee（码云）搭建 Markdown 图床，这套组合解决的就是图片"有去无回"的核心痛点，而且完全免费、国内访问速度快、管理图片像管理代码一样方便。这篇文章会把整套方案的搭建过程、每个配置字段的实际作用、以及我踩过的那些教程里从来不写的坑，全部拆开讲清楚。不管你是刚开始用 Typora 的新手，还是写技术博客已经写到瓶颈的老手，照着这套思路配置一遍，后续写文章附图的体验会顺畅很多。

1. 为什么图床方案要选 Gitee 而不是其他方式

1.1 图片丢失的本质：Markdown 里的图片路径是"相对世界"

Markdown 文本本身不能"包含"图片，它只能通过引用路径来展示图片。这个路径可以是本地绝对路径（D:\笔记\截图\00.png）、相对路径（./images/00.png），也可以是网络 URL（https://xxx.com/00.png）。

前两种方式都依赖你当前的设备。本地绝对路径换一台电脑就找不到；相对路径只要文件夹位置移动，图片也全部失效。只有网络 URL 是稳定的——图片已经上传到了某个服务器上，任何时候、任何设备打开这篇文章，只要 URL 还在，图片就能加载。

图床干的事，本质上是把图片从"本地相对世界"搬到"网络绝对世界"。当你在 Typora 里粘贴一张图片，它能自动帮你完成"备份到服务器 + 生成 URL + 替换 Markdown 引用"这一整套动作，这就是我们常说的 Typora 图床功能。

1.2 备选方案的实际体验对比

我并不是一开始就用 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 用户名，传一张图报一堆 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 这三个状态：

一个很容易被忽略的细节：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 里点上传，结果出了问题不知道是仓库、插件还是编辑器的问题。按顺序穿好每一节，任何一个环节出故障你都能第一时间定位到那个具体的组件。我自己就是这么一步步试出来的，把这套顺序记在脑子里，比你反复翻教程管用得多。