Gitee+PicGo搭建免费图床：从仓库配置到Typora自动上传全指南

1. 为什么我最终选了 Gitee + PicGo 这套方案

1.1 图床解决的是本地图片的“离家出走”问题

先说背景。我平时写技术笔记、维护个人博客，基本每个文档里都塞满截图。最开始的保存方式很简单：图片放在本地文件夹，文档里用相对路径引用。这个方案在单台设备上很愉快，但搬运几次之后就出问题了。换电脑、重装系统、把 Markdown 文件发给朋友、部署到博客服务器，只要图片没跟着一起走，页面就裂得一塌糊涂。

后来我尝试把图片统一丢到一个公共目录，再手动复制到服务器。结果更痛苦：一张张上传，一张张复制链接，遇到图片多的文章，光配图就能耗掉半小时。说实话，那段时间我一度很抗拒在文章里放截图。

图床就是专门解决这个问题的：它把图片放到一个可公开访问的存储位置，自动生成稳定的直链。你在任何设备上打开文章，图片都从那个地址加载，跟本地文件没有任何关系。简单说，图床相当于给图片找了一个“公共停车场”，文章里只需要记录车牌号，而不需要把车停在自家客厅。对写博客、记笔记、做知识库的人来说，这几乎是刚需。

1.2 主流图床方案横向对比

确定要搭图床之后，我在几种方案里犹豫过。把它们放在一起对比会更直观：

从表格能看出，几乎没有“零成本、零维护、还无限容量”的方案。对我这种图片量不大、但希望全程自动化的人来说，代码托管平台仓库是最合适的起点。它的容量不是无限，但放普通的博客配图和笔记截图，用上一段时间完全没问题。而且这个方案的搭建成本极低：一个仓库、一个桌面工具、一份令牌，十几分钟就能跑通。

1.3 为什么偏偏是这两个工具

选 Gitee 仓库当存储，核心原因是访问速度。写博客的人大多希望国内读者打开页面时图片能正常显示，Gitee 的 raw 链接在国内加载速度相对更稳，而且直链不需要登录，Markdown 里直接写链接就能访问。相比某些维护并不稳定的公共图床，代码仓库至少是正经的版本管理服务，数据丢失的概率要低得多。

选 PicGo 当上传工具，是因为它把“上传”这件重复劳动变成了拖拽或复制。PicGo 是一款开源的桌面端图床上传工具，支持 Windows、macOS 和 Linux，图形界面清晰，安装好对应插件就能对接各种图床服务。Gitee 不是它内置的首选服务，好在插件社区里有第三方 Gitee 上传插件，装好后配置一下仓库信息和令牌，就能实现“拖图即传、自动回填链接”。

强调一下这套组合的边界：它适合个人写作和低流量场景。如果你运营的是一个日访问量很大的站点，请直接考虑对象存储，别有侥幸心理。这类仓库的流量和容量限制决定了它不是为大规模外链设计的，这个问题我会在后面的注意事项里再展开。

2. 动手前必须搞懂的三件事：公开仓库、私人令牌与分支名

2.1 公开仓库：图床直链的前提

代码托管平台仓库有两种可见性：公开和私有。图片要能被陌生人直接访问，仓库就必须是公开状态。因为图床生成的是直链，访问直链时不会携带任何登录信息，服务器看到的是一个匿名请求。如果仓库是私有，那么这个匿名请求自然会通不过校验，图片链接自然打不开。

我见过不少朋友在这里踩坑：仓库建好了、PicGo 也配置完成了、上传也显示成功，结果图片死活打不开。最后翻到仓库设置一看，可见性是私有。改成公开，刷新页面，图片立刻正常。这个来回折腾的经历很典型，问题不大，但特别影响心情。

但也正因为要公开，有一条底线必须说清楚：不要往图床仓库里放任何涉及隐私的东西。拿它当图床，只存放你愿意让所有人看的图片。身份证照片、内部截图、密码备注之类的东西，一张都别放进去。这个仓库不是保险柜，是展厅，任何访问者都可能看到里面的内容。

2.2 私人令牌：PicGo 进入仓库的钥匙

PicGo 要往你的仓库里传文件，靠的不是用户名密码，而是私人令牌。你可以把令牌理解为一把带权限的钥匙：拿着它能调用平台 API，替你完成上传动作。Gitee 在账号设置里提供生成私人令牌的入口，生成时可以勾选权限范围。

这里有两个原则。第一个是权限最小化，只需要给令牌开通项目相关的权限，不需要把账号全部能力都授权出去。第二个是令牌要像密码一样保管，生成后往往只显示一次，你应该立刻存到本地密码管理器里，而不是随手贴在收藏夹或共享文档中。令牌一旦泄露，别人就可能利用它给你的仓库塞文件，所以定期检查、泄露即重置是好习惯。

有刚开始接触的人会问：PicGo 里直接填账号密码不行吗？大多数平台的 API 不接受这种方式，明文密码权限太大、风险太高。令牌机制可以把能力限制在“上传文件到指定仓库”这个小范围内，即使泄露，损失也相对可控。不要嫌多这一步麻烦，安全习惯本来就是几个小动作堆出来的。

2.3 分支名：链接里最容易填错的一项

第三个关键概念是分支名。代码仓库默认都有一个主分支，过去常见的是 master，有些新仓库也可能是 main。PicGo 上传文件时，需要明确告诉它传到哪个分支。如果你填写的分支名和仓库实际的分支名不一致，上传就会报错，或者文件被传到了意料之外的分支上。

链接地址里也经常带分支名。以 Gitee 为例，直链通常长这样：域名后面跟着用户名、仓库名、分支名、文件路径。只要分支名、仓库名、路径任意一个和实际情况对不上，返回的就是 404。所以说，配置前最好打开仓库页面确认一下当前默认分支，不要凭记忆填写。

我第一次配置时就是想当然地填了 master，实际仓库创建时默认分支是 main，结果上传一直失败。看完日志才发现是分支名写错。这个错误特别低级，但非常容易犯，所以放在最前面提醒你。配置这种事，越是对照着真实页面来，越不容易出错。

3. Gitee 仓库创建与令牌生成全流程

3.1 新建一个容量规划好的图床仓库

搭建的前两步都在 Gitee 网页端完成。第一步是登录账号，进入仓库列表，点击“新建仓库”。仓库名建议起得简短一些，比如 images、pics、blog-assets 这类，因为仓库名会直接出现在生成的图片链接里，名字太长会让链接变得很臃肿，后面写文章引用时也不方便。

可见性记得选择公开。如果不确定，可以这么想：图床图床，图的“床”就是公开仓库，图片本身必须是可公开访问的资源。新建的时候可以顺便勾选“使用 Readme 文件初始化这个仓库”，这样仓库里会有一个说明文件，方便你在网页端确认仓库是否创建成功，也让仓库不至于完全空白。

还有一个容易被忽略的点：单独用一个仓库放图床，不要跟代码项目混在一起。很多人图省事，把图片传到博客项目仓库里，时间一长仓库体积膨胀，代码克隆变慢，图片文件还容易在代码操作中被误删。分开管理，图床仓库只放图片，代码仓库保持干净，后续不管是备份还是清理都更省心。

仓库创建完成后，记住两件事：用户名/仓库名，以及当前默认分支。前者在 PicGo 配置里要填 repo 字段，后者要填 branch 字段。打开仓库首页，一眼就能看到分支信息，有截图的话最好存一份在配置笔记里。别小看这两条信息，配置时你会反复用到。

3.2 生成私人令牌并限制权限

第二步是生成私人令牌。打开头像菜单，进入“设置”，找到“安全设置”，里面会有“私人令牌”入口。点击生成新令牌，平台会让你选择权限范围。对图床场景来说，勾选项目相关权限即可，不要全选，保持最小化授权原则。

生成之后，令牌只会出现一次。我特别强调这一点，是因为我见过有同事把令牌页面开着就去做别的事，回头发现页面已刷新，令牌再也看不到了，只能重新生成。正确的做法是生成后立刻复制，保存到密码管理器里，或者放在一个只有你能访问的文件中。万一忘记保存，最简单的处理就是重新生成一个，没必要找回旧的。

保存好令牌后，建议马上做一个验证：在网页端上传一张测试图片到仓库，确认整条链路是通的。再回到 PicGo 配置时，如果后面上传失败，你能更快定位是令牌问题还是配置问题。这是个小习惯，但能省下不少排查时间。尤其是第一次接触这套流程的人，多验证一步会少踩很多坑。

4. PicGo 安装、插件配置与首次上传

4.1 安装 PicGo 并准备好 gitee 插件

PicGo 的下载和安装没什么特别之处，去它的发布页找对应系统的安装包，Windows 装 exe，macOS 装 dmg，Linux 按对应发行版安装即可。安装完成后打开，界面主要分为上传区、相册区、图床设置和插件设置几个模块，功能分布很直观，用一两次就能熟悉。

Gitee 支持不是内置的，所以要先在插件市场里装一个 Gitee 上传插件。操作方式是进入“插件设置”，在搜索框输入 gitee，会看到相关的第三方插件。选择下载量高、更新时间较新的那一个，点击安装。安装完成后，建议重启一下 PicGo，让插件正常加载。

如果遇到插件安装失败，先检查本机网络到插件市场是否正常，再确认 PicGo 版本是否过旧。插件市场里的插件通常跟着 PicGo 主版本走，如果版本跨度太大，兼容性问题会导致插件装完也用不了。升级 PicGo 或尝试安装对应旧版本插件都是可行的方向。实在装不上，还可以去插件的发布页手动下载，再导入本地安装包，这个流程稍微绕一点，但能解决一部分网络或版本问题。

装好插件后会看到图床设置列表里多了一个 Gitee 图床的入口。点进去，就是接下来要逐个填写的配置项了。

4.2 图床配置字段逐项说明

Gitee 插件的配置项不算多，但每个都和上传结果直接相关，我按字段逐一说明。

repo 字段：填“用户名/仓库名”，例如账号是 yourname，仓库名是 images，这里就填 yourname/images。这是 PicGo 确认上传目标的依据，填错会直接导致上传失败。

branch 字段：填仓库的默认分支名，多数 Gitee 仓库是 master，但创建时如果平台默认是 main，也要以实际页面为准。

token 字段：把上一步生成的私人令牌完整粘贴进来。这里没有省略号或模糊匹配，必须一字不差。

path 字段：图片在仓库里的存放目录。建议填一个带层级的前缀，比如 imgs/ 或者 images/blog/，不填的话图片会直接堆在仓库根目录，时间久了非常难管理。

customPath 字段：控制是否按日期自动创建子目录。这个字段支持动态格式，常见用法是 {year}-{month}，这样每天上传的图片会自动归到当月的文件夹里。启用之后，仓库的目录结构会一直保持有序，值得开启。

customURL 字段：自定义访问地址前缀。如果你有额外的加速服务或者专门绑定了域名，可以在这里改；普通用户留空即可，默认会使用平台提供的直链。

填完后点击“设为默认图床”，再保存。这里要提醒一句：不同版本插件，个别字段名可能略有差异，比如有的版本写作 customPath，有的写作“自定义路径”。按界面提示来，逻辑是一样的。如果你用的插件版本比较老，还可以参考它的配置文件，里面通常有注释说明。

4.3 首次上传测试，别跳过这一步

配置完成后，直接进入上传区做一次完整测试。拖一张小尺寸的测试图进去，正常的话会看到上传成功提示，并返回一个以仓库地址开头的链接。复制这个链接，打开浏览器访问，确认图片能正常渲染，然后回到仓库页面看看文件是否出现在了预期目录。

这一步非常重要，它同时验证了仓库可见性、令牌权限、分支名和路径设置四项内容。如果上传成功但链接打不开，问题大概率出在仓库可见性或分支名上；如果上传直接报错，重点排查令牌权限和 repo 字段。宁可多花这一分钟，也别等写到一半才发现图床根本不可用。

首次测试通过之后，可以多传两到三张不同类型的图片，对比不同尺寸和格式的表现。顺手把返回的链接格式记下来，后面手动拼链接或排查问题时都有参考价值。我自己的习惯是建一个专门存放测试图片的测试目录，传完就删，避免污染正式内容。

5. 把图床接入写作工作流：Typora 与批量场景

5.1 Typora 设置自动上传，粘贴截图即成链接

图床搭好只是第一步，真正让效率提升的是“截图即上传”的工作流。我常用的 Markdown 编辑器是 Typora，它自带图片上传功能，可以调用外部工具。在 Typora 的偏好设置里找到“图像”，把插入图片时的动作设置为“上传图片”，上传服务选择 PicGo（app）。

具体路径可能因版本不同而略有差异，但核心逻辑一致：Typora 在检测到文档里有本地图片时，会把图片信息交给 PicGo，PicGo 完成上传后返回远程链接，Typora 再把文档里的本地路径替换成这个链接。整个过程不需要手工复制 URL，也不需要切换窗口。

设置好之后，验证一下。任意截一张图，直接在 Typora 里粘贴。正常情况下，文档里会短暂出现一个本地上传提示，几秒后图片正常显示，你查看图片地址，发现它已经变成了远程链接。此后写文章、记笔记，只需要截图粘贴，剩下的全部自动完成，体验非常顺滑。图片多的时候尤其能感受到差别，原来半小时的配图工作，现在一分钟都不用。

如果你遇到 Typora 提示上传失败，优先确认 PicGo 是否已经打开，并且 PicGo 的服务模块是否在运行。很多编辑器通过本地服务端口和 PicGo 通信，PicGo 没启动，编辑器自然调用不到。把 PicGo 放进系统开机启动项，可以避免很多类似的“突然失败”。

5.2 其他写作和发布场景的整合

除了 Typora，Obsidian、Notion 这类笔记软件也有各自的图片自动上传插件，多数是调用 PicGo 的服务端口，工作原理相似。需要说明的是，不同插件的文档成熟度不同，配置时留意插件说明页面里的字段含义，基本都能在十分钟内搞定。不要一上来就装十几个插件，先跑通一个最常用的流程，再逐步增加。

发布静态博客时，图床的作用尤其明显。以前我把图片放在站点仓库里，每张图片都会占用部署体积，而且文章里的相对路径一旦调整就要大改。使用图床后，所有文章图片都是独立外链，发布时不再关心图片文件是否被一起打包，换主题、换目录结构也不会再有裂图问题。

批量场景也值得聊聊。如果你有一批本地图片需要全部转成图床链接，可以在 PicGo 上传区多选批量上传，或者直接把整个文件夹的图片拖进去。上传速度取决于单张大小，传完以后把所有返回链接整理到文本文件里，再替换文档里的引用位置即可。

5.3 图床与仓库管理的几个好习惯

长期使用下来，我总结出几个值得养成的习惯。图片目录按日期分好，开头用 customPath 自动生成就是其中之一。这样一年下来，仓库里是 2024-01、2024-02 这样的清晰结构，找图、清理、备份都方便。

另外要定期压缩图片。截图尽量转换成 JPG 或 WebP，单张控制在几百 KB 以内，而不是截图后原样上传。对个人博客来说，当图片加载变慢时，原因往往不是网络，而是原图太大。一张几 MB 的截图会让文章打开速度明显下降，压缩过后体验会好很多。

不要随意清理仓库里的历史图片。删除前先确认没有文章还在引用这条链接，否则文章里会突然多出一堆裂图。如果只是一时觉得没用的图，可以先移到“待删除”目录，过段时间再统一处理。还要定期查看仓库容量和上传记录，尽早感知是否接近限制。我对仓库容量的态度是：尽量把它用在刀刃上，保留的都是需要的配图，不把图床仓库当作长期文件备份库。

6. 高频问题与排查记录

6.1 四类常见报错及解决思路

把实际上传中可能遇到的问题整理成速查表，方便你遇到时对着排查：

排查顺序有个小技巧：先看错误码。401/403 一定先查令牌，404 一定先查路径，5xx 再考虑是不是平台服务临时波动。不要把问题复杂化，百分之七八十的报错都出在仓库可见性和分支名这两个地方。日志里通常会有更详细的提示，PicGo 的日志面板就是排查的第一现场。

6.2 新手最容易忽略的几个安全与性能细节

第一个是令牌泄露风险。不要在博客工程、公开文档、聊天记录里直接粘贴私人令牌。一旦泄露，立即到平台重置，不要拖。第二个是公开仓库的隐私边界。图片只要进了公开仓库，就等同于被任何人看到，隐私信息、账号截图这类图片一律不要传。不要觉得“只是自己写笔记不会有人看”，公开仓库的地址一旦被搜索引擎收录，传播面是你控制不了的。

第三个是性能预期管理。代码仓库本身不是为高并发外链设计的，如果文章里一次引用了几十张大图，页面加载难免变慢。合理的做法是控制文章图片数量，并对原图做压缩。第四个是备份意识。图床仓库同样要做好备份，我一般每隔一段时间把仓库整体拉一份到本地，一旦误删还能恢复。备份文件不需要很复杂，一个 git clone 就能解决。

6.3 我的真实踩坑：分支名不一致引发的 404

分享一个我实际踩过的坑。有一次我在新平台创建图床仓库，默认分支变成了 main，但我没有注意，PicGo 配置还留着旧的 master。上传时工具显示成功，但打开链接永远是 404。我当时以为是令牌失效，反复重试几次都没解决，最后静下心看日志，才发现分支名不对。

解决的方法也很简单：打开仓库页面，复制实际分支名，替换 PicGo 配置，重新上传。这件事给我的教训是，一切以仓库实际状态为准，不要相信记忆里的“默认值”。遇到 404，至少应该先回归仓库、分支、路径这三项，而不是盲目重置令牌。排查问题也是一样，先从最容易检查的配置入手，再往深层找。

6.4 顺手再分享一个个人体会

用了这套方案很长一段时间后，我的体会是：图床工具的价值不只在于“上传”，更在于“自动化”。当你把上传从手工操作里剥离开，写作的注意力才能真正集中到内容本身。Gitee 配合 PicGo 搭起来很快，稳定性和访问速度对个人场景也够用，但始终要记住它有一套容量和流量的边界。

如果有一天你的图片数量明显变大，或者站点访问量上来了，可以考虑把存储整体迁移到对象存储，图片链接的前缀是全局替换的，迁移成本并不像想象中那么高。前期只要建好目录规范，后期无论留在仓库还是迁走，都从容得多。这套方案不完美，但作为个人知识库的基建，它已经非常有价值了。