笑技图床这东西，玩博客、写技术文档、做产品介绍的人迟早都会碰到。说穿了，图床就是给图片找一个“带外链地址的存放处”，写文章时引用这个地址，别人打开页面就能加载图片，而不是把所有图片都塞进文档或项目目录里。几年用下来，我个人最省心的方案就是 Gitee 仓库加 PicGo 工具这套组合：免费、国内访问快、配置过程直观，最关键是上传完图片会自动生成 Markdown 链接，配合 Typora 这类编辑器基本可以做到截图即贴、贴完即用。这篇文章就从最基础的原理讲起，把仓库创建、令牌申请、插件配置、常见报错全部梳理一遍，适合刚接触图床的新手，也适合想从公共图床迁移到自建图床的博客用户参考。
1. 为什么要自建图床：需求场景与方案选型
1.1 图床到底解决了什么问题
不写 Markdown、不发博客的人可能不太理解：图片直接放在文章旁边不行吗？问题在于，图文混排的文章一旦要发布到博客、社区、公众号等多个平台，每张图片都会被平台重新处理、重新存储，你在本地排好的格式很可能全乱。更麻烦的是，如果文档里嵌的是本地磁盘路径，换了电脑就变成一堆裂图。
图床的本质是“把图片托管在一个稳定的公共地址上”，Markdown 文档里只保留一行链接。这样文章源文件可以随时移动、同步、换编辑器，稿件拿到任何地方都能正常渲染。我自己维护一份技术笔记、几个项目 README、偶尔写点长文，图片全部走图床，历史文章里的图片链接到现在还稳定可用，这一点是本地存储永远替代不了的。
除了博客场景，图床在论坛发帖、产品原型说明、给客户写交付文档、甚至聊天工具里分享长图这些场景也都很实用。说白了，凡是“引用图片需要跨平台保持稳定”的地方，图床都有用武之地。
1.2 为什么是 Gitee 加 PicGo 这套组合
市面上的图床方案很多，但 Gitee 仓库加 PicGo 的组合有几个很实在的优势。
首先是存储免费。Gitee 作为代码托管平台，仓库空间本身就是免费的，图片本质上是“代码仓库里的普通文件”，只要体积控制得当，基本不会有额外费用。其次是访问稳定。Gitee 平台在国内，服务器节点对国内用户友好，图片链接在各网络环境下刷出来的速度都比较稳，这一点对于博客访客在国内的情况尤其重要。
PicGo 的价值则在于“一整套上传体验”。它是个桌面端工具，支持把剪贴板里的截图直接上传、拖拽图片上传、监控截图保存路径自动上传，上传完成后会自动把链接以 Markdown 格式复制到剪贴板。配合 Gitee 仓库使用，相当于拥有一个“个人专属图床”，图片还能按目录结构管理，比公共图床可控得多。
这套组合还有一个隐性优点：仓库本身带 Git 历史。哪天误删了图片，或者想找回旧版本，直接在仓库历史里操作即可，这种版本管理能力是普通图床给不了的。
1.3 其他方案对比：为什么最终选了它
| 方案 | 成本 | 稳定性 | 主要门槛 | 适用人群 |
|---|---|---|---|---|
| 公共图床（如 SM.MS） | 免费 | 依赖服务商运营，有丢图与访问慢的隐患 | 基本无门槛，注册即可用 | 随手传图、临时分享 |
| 云厂商对象存储（如阿里云 OSS、腾讯云 COS） | 按量付费，价格不贵 | 高 | 通常要绑定备案域名，配置稍重 | 正式站点、对速度和服务有要求的场景 |
| 代码托管平台仓库当图床（Gitee 或同类平台） | 免费 | 中高，取决于平台策略和仓库容量 | 需要一次性配置令牌和上传工具 | 个人博客、文档写作、长期引用 |
我最早也用过公共图床，确实省心，但心里总不踏实：免费服务说关停就关停，链接一旦失效，历史文章全变白板。云厂商方案是好，但为了图床单独去买域名、弄备案，对纯写作者来说有点重。Gitee 仓库存图片等于“借鸡生蛋”，成本为零，而且我对 Git 仓库的内部结构一目了然，心里踏实。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 准备工作：注册仓库与申请令牌
2.1 注册账号与新建仓库的要点
如果是第一次用 Gitee，先注册账号并完成邮箱或手机号验证。然后进入仓库管理页，点击新建仓库。仓库名称建议用英文小写，比如 img-beds、pic-storage 这种，后面链接里会直接用到，中文名称容易出现编码问题，尽量不要用。
这里有一个很重要的动作：在新建仓库页面里勾选“使用 README 文件初始化仓库”。这样做的好处是仓库会立刻生成一个默认分支，避免后面拿到一个完全空仓库、连分支名都要靠猜的尴尬。初始化完成后，记下三样信息：登录用户名、仓库名称、默认分支名。这三样是后面配置的核心参数，缺一个都传不上图。
仓库的公开性也要在这一步想清楚。图床仓库必须设为公开，因为图片链接要被外部访问；私有仓库里再多的图，拉到外部照样 404。新建时直接选公开，或者先建私有、后续在仓库设置的“开源”选项里转公开都行，但务必记住：私有状态下的图片链接是不通外网的。
2.2 生成私人令牌的完整流程与权限说明
PicGo 上传图片到 Gitee 仓库，本质是调用 Gitee 的官方接口。接口调用不能直接用账号密码（平台也不允许这么干），所以需要一个私人令牌作为“通行证”，这个令牌具备在指定仓库里创建文件的权限。
生成路径是：右上角头像进入个人设置，找到安全设置里的“私人令牌”模块，点击生成新令牌。流程中会让你填写令牌描述，比如“图床上传专用”，然后选择权限范围。这里我只勾选了 projects（仓库读写），这个权限足够执行上传操作了。令牌生成后会展示一次，务必立即复制保存到本地密码管理器里，因为页面刷新之后就不会再显示了。
很多新人在这里踩坑：生成令牌后没有立刻保存，后面配置时找不到，只好重新生成一次。另外一定要清楚，这个令牌本质上和密码等权，谁拿到它就能往你的对应仓库里写文件，不要把它提交到任何公开仓库，也不要随手发到聊天群里。真泄露了，回到令牌管理页删掉旧的、重新生成一个就行。
2.3 仓库公开、分支名、路径规划三个前置条件
配置之前，先把三个容易忽略的点确认好，能省下后面一大半的排查时间。
第一，仓库确实已经公开。可以在仓库主页查看是否显示“公开”标识。第二，确认分支名。Gitee 新建仓库的默认分支通常是 master，但老仓库、迁移仓库或不同初始化方式可能导致分支名不同。建议直接打开仓库文件列表，看地址栏里显示的分支名是什么，或者看仓库首页那颗分支按钮上的文字。第三，规划好目录结构。不要把所有图片都堆在仓库根目录，建议在仓库里建一个 img 或 images 目录，里面再按年份分目录。前期随手传还好，传了半年之后想找一张祖师爷级别的老截图，没有目录规划只能翻到崩溃。
路径规划还直接影响链接长度。仓库路径越深，图片链接越长，虽然不影响使用，但扔在文章里既占篇幅又不美观。我的习惯是仓库根目录下建一个两级结构：img/年份/，对应图片链接就是类似 gitee.com/用户名/仓库/raw/master/img/2025/图片名.png，清楚又好管理。
3. 安装 PicGo 并配置 Gitee 上传插件
3.1 下载安装与运行前的环境确认
PicGo 有桌面客户端和命令行版本，绝大多数人用桌面客户端就够了。去官方网站下载对应系统的安装包，Windows 和 macOS 都支持，Linux 用户也可以用客户端或直接用命令行模式。安装完成第一次启动时，程序会缩到系统托盘，背景监听剪贴板和截图事件。
启动后先在设置面板里过一遍基础项。我习惯勾选“上传后自动复制链接”，这样上传一完成，Markdown 格式的图片链接就已经在剪贴板里，到编辑器直接粘贴即可。“提示音”我也开着，上传成功会有一声提示，截图批量处理时不用一直盯着界面。其余设置保持默认就行。
有一点要注意：PicGo 的系统托盘和关闭按钮容易混淆，关掉窗口不等于退出程序。如果发现剪贴板里的图片没有自动上传，先看看托盘图标还在不在，很可能只是窗口关了，后台还活着。
3.2 安装 Gitee 上传插件
PicGo 默认内置了几家常见图床的配置项，但 Gitee 不在其中，需要额外安装社区开发的插件。打开 PicGo 的插件设置页面，在搜索框里输入 gitee，会出现相关的上传插件，点击安装即可。
插件安装走的是 npm 机制。如果你遇到安装进度条长时间转圈或者提示安装失败，大概率是网络源的问题。PicGo 提供了插件安装源的自定义入口，把它切换成国内镜像源之后再重试，成功率会高很多。这个操作属于正常的软件源配置，不需要额外工具。
安装完成后，PicGo 左侧图床设置区域会多出一个“Gitee 图床”的配置入口。如果没有看到，把 PicGo 重启一次；极少数情况下需要完全退出进程再重新打开才能识别新插件。插件本身不需要单独启动，它只是给 PicGo 扩展了一个新的上传目标。
3.3 逐项填写上传配置：每一个字段的含义
进入 Gitee 图床配置页，会看到几个关键输入框。这里逐个说明：
| 配置项 | 填写内容 | 说明与建议 |
|---|---|---|
| repo | 用户名/仓库名 | 格式必须严格带斜杠，比如 demo_user/img-beds；用户名是登录用户名，不是仓库主页上显示的个性昵称 |
| branch | master 或其他分支名 | 以仓库实际默认分支为准，写错分支上传必失败 |
| token | 私人令牌 | 粘贴第 2.2 步保存的令牌，不要有多余空格 |
| path | img/2025/ | 仓库内目录，可留空表示根目录；建议按实际规划填写 |
| customUrl | 自定义域名或加速前缀 | 可选；留空时使用 Gitee 默认拼接规则 |
这里重点说三个细节。
repo 字段最容易被“昵称”误导。用户主页显示的名字可以是任意中文昵称，但接口要求的是登录用户名。不确定的话，打开 Gitee 个人主页，看地址栏里那串英文才是真正的用户名。
branch 字段同样关键。仓库默认分支是 master 就填 master，是 main 就填 main。这个字段和 repo、path 共同决定 API 请求路径，只要有一项不匹配，返回的要么是 404，要么是莫名其妙的报错。
path 字段末尾的反斜杠不是必须的，但建议统一格式。留空时图片直接上传到仓库根目录，文件一多就会很乱；填了目录路径后，PicGo 会按照你在仓库里建好的目录结构上传。如果目录不存在，也可以直接在 path 里写一个全新的目录名，插件会自动创建。
配置完成后先不要急着批量传图，在 PicGo 上传区拖一张普通图片测试。看日志输出是否提示成功，看相册区是否出现图片记录，主要是验证 repo、branch、token 三项。输出格式正确的话，图片会传到你指定的仓库目录下，并且自动生成链接。
4. 实操验证：从截图到 Markdown 链接的全流程
4.1 第一次上传测试与链接结构解读
测试上传一张名为 hello.png 的图片，假设配置为：用户名 demo_user、仓库 img-beds、分支 master、path 为 img/2025/。上传完成后，剪贴板里得到的链接是：
https://gitee.com/demo_user/img-beds/raw/master/img/2025/hello.png
拆开看这个链接，其实就是固定的拼接规则：仓库地址 / raw / 分支名 / 仓库内路径 / 文件名。理解了这个规则，排查问题时思路会清晰很多——链接打不开，就是这四个部分某一个出了问题。raw 是关键标识，表示取仓库文件的原始内容，图片会以二进制方式直接输出，浏览器打开就是图片本身。
PicGo 默认复制的是 Markdown 格式，也就是带感叹号和方括号的那一串。如果你需要纯 URL 格式，可以在设置里切换链接格式为 URL，传完直接得到纯链接，适合贴到论坛签名、聊天工具这类不支持 Markdown 的地方。
4.2 截图自动上传、剪贴板监听与快捷键
实际写文章时，最顺手的流程不是每次都手动拖图片，而是让 PicGo 自己监听系统剪贴板。截图工具截完图，图片已自动进入剪贴板，PicGo 在后台检测到剪贴板里有图片，就会开始自动上传，上传完自动把链接复制回剪贴板。整个过程手都不用离开键盘，体验非常好。
这个功能默认不一定开启，要在 PicGo 设置里确认“剪贴板图片上传”或类似的监听选项已经打开。有人会遇到截图后迟迟没有上传动作，大概率是监听开关没开，或者程序窗口关闭后进程实际退出了。
PicGo 还支持全局快捷键，比如自定义一个快捷键用于“手动上传剪贴板图片”。我习惯把截图工具、PicGo 快捷键、编辑器粘贴键串成一条流水线：截图 → 掐一下快捷键让 PicGo 上传 → 编辑器里直接粘贴出链接。遇到一次截多张图、需要手动挑选的情况，这个快捷键比自动监听更可控。
4.3 Typora 联动：写博客最舒服的工作流
Typora 是很多 Markdown 写作者的主力编辑器，它和 PicGo 的配合堪称绝配。在 Typora 的偏好设置里找到图像设置，把上传服务指定为 PicGo，并填上 PicGo 应用程序的安装路径。从此以后，在 Typora 里直接粘贴截图，Typora 会调用 PicGo 完成上传，然后把返回的 Markdown 图片链接自动插入文档。
这个流程解决了一个很实际的问题：你截图粘贴时是本地图片路径，发布时却需要外链，过去要先手动上传再替换链接，现在全部一步完成。其他支持自定义上传命令或 PicGo 插件的 Markdown 编辑器也是同样的思路，配置一次，全流程自动化。
也要说明一点：Typora 调用 PicGo 时，PicGo 必须处于运行状态。我第一次配置完遇到的现实问题是上传一直失败，检查了半天才发现 PicGo 窗口被我关掉之后进程也退出了。后来我把 PicGo 设为开机自启，就再也没因为这个问题卡过壳。
5. 常见问题与排查实录
5.1 问题速查表
把这段时间遇到的和身边朋友问得最多的报错整理成一张表，方便大家直接对照：
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
| 上传失败，接口返回 401 或鉴权失败 | token 错误、过期或权限不足 | 重新生成令牌，勾选 projects 权限，重新粘贴 |
| 上传失败，接口返回 404 | repo 格式错误或仓库不存在 | 检查是否为“用户名/仓库名”，确认用户名是登录用户名 |
| 图片上传成功，但浏览器打开 404 | 仓库是私有状态 | 到仓库管理里把仓库改为公开 |
| 图片打开 404，仓库也已经公开 | 分支名或路径写错 | 对照仓库实际分支和文件路径核对配置 |
| 上传提示文件已存在 | 仓库里同名文件已存在 | 给文件加时间戳前缀，或使用带日期的目录 |
| 插件安装一直转圈或失败 | npm 源访问不畅 | 在 PicGo 插件源设置里切到国内镜像后重试 |
| 图片能访问但加载慢 | 图片体积过大 | 压缩图片、转 WebP 格式，控制单图大小 |
5.2 逐条排查思路与实操记录
鉴权类错误是最常见的。遇到 401，我的处理习惯是：先去令牌管理页确认令牌还在且没被删除，然后检查粘贴时有没有混入空格。很多编辑器会自动把长令牌折行，复制粘贴时会把换行符也带进去，这个很难看到，但接口不认。
404 类问题要分两步排查。先打开浏览器手动访问拼出来的图片地址，看是不是真能打开。如果浏览器都 404，从链接结构反推：地址里的用户名、仓库名、分支名、路径分别打开验证，锁定是哪一段不对。这里有一个很实用的操作：登录 Gitee 后在网页里进入图片文件页，点击页面上的“原始数据”按钮，浏览器地址栏里的地址就是正确直链，拿它和 PicGo 生成的链接对比，一眼就能看出差异。
文件已存在的提示也属于高频问题。Gitee 接口不允许覆盖同名文件，同一天截图太多，如果两张图恰好同名（比如从某个软件里导出的图片都叫 export.png），第二次上传就会失败。我的解法是在 path 里带上日期目录，不同日期天然隔离；还不放心的话，可以在 PicGo 设置里开启文件重命名，上传前自动加上时间戳，彻底避免同名冲突。
插件安装失败的问题，本质是网络链路。切国内镜像源后一般都能解决。如果仍然安装不上，还有一个兜底办法：在插件市场上找到对应插件的安装包地址，手动下载后按说明放在指定目录里，重启 PicGo 也能生效。这个办法操作起来稍微繁琐，但胜在可靠。
6. 实操中的几个心得与避坑技巧
6.1 图片压缩是长期使用的前提
Gitee 仓库容量是有限的，不压缩图片的话，几个月就能塞满。更实际的影响是链接加载速度：一张 5MB 的截图和 200KB 的压缩图，只要访客网络差一点，打开体验就是天壤之别。我现在的习惯是图片统一压缩到宽度 1200px 以内、质量控制在 80% 左右，JPG 或 WebP 格式，单张控制在 200KB 上下。对博客阅读场景来说，视觉上几乎看不出差别，但加载速度和仓库容量压力都小得多。
压缩工具的选择很自由，在线压缩、截图软件自带压缩、PicGo 的部分插件也支持上传前压缩。我个人用本地离线工具居多，操作多次也稳定。这一点不算必须，但如果你打算把这个图床长期用下去，建议从第一天起就养成压缩习惯。
6.2 令牌安全与最小权限原则
前面说过令牌等于密码，这里再强调一次。我见过有人为了方便把令牌写进博客文章里，也见过有人把存了令牌的配置文件误传进公开仓库，这两种情况都很危险。一旦泄露，第一时间回令牌管理页删除并重新生成。
权限上够用就好。如果你只在 Gitee 上放图片，令牌只勾选 projects 即可。不要图省事把所有权限项目全勾上，权限范围越小，泄露后的风险面就越窄。
6.3 原图备份与仓库容量管理
图床解决的是“引用”问题，不应该承担“备份”职责。我的原则是本地磁盘保存一份原图，图床仓库里只是对外发布的副本。本地原图可以用网盘或移动硬盘做归档，图床则严格控制体积，定期清理不再使用的图片。
仓库图片多了以后还有一个管理技巧：按主题分批建仓库。比如博客图片放一个仓库，项目文档图片放另一个仓库。这样做的好处是单一仓库容量压力小，哪天某一个仓库出了问题，也不会影响所有文章里的图片链接。说到底，图床方案要从“能跑”变成“长期稳定跑”，靠的还是合理的目录规划和适度的容量管理。
6.4 留着本地副本再清库
清理图床仓库里的过期图片时，务必先确认本地或备份里有对应原图。我吃过这个亏：某次为了给仓库腾空间，直接把一个年份目录整个删了，后来翻旧文章需要配图时才想起来，有些历史配图只在图床里存过，本地根本没留版本。现在我的清理流程是：先从仓库下载需要清理但本地可能没有的图片，核对一遍，再用忽略库或直接删除的方式处理。稳一点，仓库少传几张图不重要，历史文章配图找不回来才是真麻烦。
这套 Gitee 加 PicGo 的图床方案，我前后搭配着跑了好几年，中间也换过其他思路，最后还是觉得它最贴合个人写作场景。它的价值不在于技术多高深，而在于把“传图、拿链接、贴进文档”这三件琐事压成了一次操作。配置过程大概十分钟，之后每天写文章都在省时间。如果你现在还在为公共图床的不稳定头疼，或者正打算给博客配一套免费靠谱的图片方案，按文章里的步骤从仓库开始搭一遍，应该很快就能感受到“截图即链接”的顺畅感。