1. 为什么写博客的人最后都会折腾图床这件事如果你写 Markdown 笔记或者博客超过三个月大概率会遇到一个很烦的问题本地截图粘贴进去图片路径是C:\Users\XXX\Pictures\screenshot.png这种。自己电脑上看着好好的一旦把笔记同步到另一台设备、发给别人、或者发布到静态博客上图片全部裂开。更别提用 Typora 写文章时截图粘贴进去默认存到本地某个临时目录时间一长自己都找不到图在哪。解决这个问题的核心思路就一句话让图片有一个公网可访问的 URLMarkdown 里只存这个 URL而不是本地路径。承担把图片存起来并给出 URL这个角色的服务就是我们常说的图床。图床方案大致分三类。第一类是公共免费图床上传即用但随时可能跑路或者限速图片说没就没写长期内容的人基本不敢用。第二类是自己买对象存储比如各家云厂商的 OSS/COS稳定但要花钱还要配置密钥和防盗链。第三类是用代码托管平台的仓库当图床把图片当成仓库文件提交上去通过平台的原始文件链接访问。第三类里最常被提到的就是 Gitee码云方案配合 PicGo 这个上传工具再和 Typora 打通形成截图→自动上传→自动替换为 URL的完整链路。这套方案适合谁适合个人写笔记、写博客、做技术文档的人尤其是对成本敏感、又希望图片相对可控的。它不适合对可用性要求极高的商业场景因为仓库图床本质上是在借用代码托管平台的文件服务平台规则一变你就得跟着调整。这一点我后面会专门讲。整条链路其实只有三个角色Typora 负责写作和触发上传PicGo 负责执行上传动作Gitee 仓库负责存储并提供访问链接。把这三个角色各自的职责和它们之间的接口搞清楚配置就是十分钟的事。但真正让人卡住的往往不是配置本身而是几个隐藏的坑比如图片链接防盗链、仓库文件大小限制、PicGo 插件版本不匹配等等。下面我按实际搭建顺序把每一步的原理和踩坑点都拆开讲。2. 动手之前先把三个角色的职责理清楚2.1 Typora 的图片处理逻辑它只是个触发器很多人误以为 Typora 自己会上传图片其实不是。Typora 在图片这件事上只做两件事一是检测到你粘贴或插入了图片二是根据你的设置决定这张图怎么处理。它的处理方式有几个选项在偏好设置 → 图像里能看到无特殊操作图片就存本地路径原样写进 Markdown。复制到指定路径把图片复制到你指定的文件夹Markdown 里写相对路径。上传图片调用一个外部命令或工具把图片传走然后把返回的 URL 写进 Markdown。我们要用的就是第三种。Typora 本身不内置任何图床的上传能力它通过调用PicGo 的命令行接口或者配置自定义命令来完成上传。所以 Typora 在这里的角色非常纯粹它是个触发器负责发现新图片和把上传结果写回文档。理解这一点很重要因为当上传失败时你要判断的是是 Typora 没触发上传还是 PicGo 上传失败了还是上传成功但 URL 没写回来。这三个环节出问题排查方向完全不同。2.2 PicGo 的定位一个可插拔的上传中枢PicGo 是一个开源的图片上传工具有图形界面GUI也有命令行CLI。它的设计很聪明核心只负责管理图床配置和调度上传具体传到哪个平台靠插件实现。比如传到 Gitee 需要装picgo-plugin-gitee-uploader传到其他平台各有各的插件。这种插件化设计带来的好处是灵活坏处是插件质量参差不齐版本兼容问题很常见。我见过最多的报错就是插件装上了但上传报 404 或者 403八成是插件版本和 PicGo 主程序不匹配或者插件配置里的分支名、路径写错了。PicGo 还有一个关键能力它启动后会开一个本地 HTTP 服务默认端口 36677Typora 就是通过这个本地接口把图片喂给 PicGo 的。所以PicGo 必须处于运行状态Typora 才能上传成功。这一点新手特别容易忽略关了 PicGo 窗口以为没事结果 Typora 上传一直失败。2.3 Gitee 仓库存储层和它的边界Gitee 仓库在这里承担的是文件存储 公网访问两个职责。你把图片提交到仓库的某个目录Gitee 会为每个文件生成一个可访问的链接格式大致是仓库地址加上文件路径。Markdown 里存这个链接任何能上网的地方都能看到图。但用仓库当图床必须清楚它的几个边界这些边界直接决定了你的方案能不能长期用边界项具体情况对使用的影响单文件大小平台对单文件有大小限制大图、长截图可能传不上去需要压缩仓库容量免费仓库有容量上限图片多了要考虑清理或分仓库访问频率对高频访问有限制图片被大量引用时可能加载慢或被限防盗链部分平台对原始文件链接有 referer 校验外站引用可能显示裂图内容审核仓库内容可能被审核图片内容需合规否则仓库可能受限提示把仓库当图床本质是借用平台的文件服务。平台规则随时可能调整所以重要图片建议本地留一份备份别把仓库当成唯一存储。理解了这三个角色后面的配置就是按部就班。我建议你在动手前先想清楚一件事你是要一个能用就行的方案还是要一个相对稳定、可维护的方案。前者十分钟搞定后者需要在仓库结构、图片命名、备份策略上多花点心思。下面我按稳定方案来讲。3. Gitee 仓库的准备工作不只是建个仓库那么简单3.1 建仓库时的几个关键选择新建仓库时有几个选项直接影响后续使用我逐个说下我的选择理由。仓库公开还是私有。这是第一个要决定的。私有仓库的图片链接需要登录才能访问意味着你博客里的图别人根本看不到所以图床仓库必须设为公开。但公开就意味着任何人都能浏览你的图片所以别往里传敏感内容。我的做法是专门建一个只放图片的仓库和代码仓库分开避免混在一起管理混乱。是否初始化 README。建议勾选这样仓库建好就有一个默认分支和一次提交PicGo 上传时不会因为空仓库报错。空仓库在某些插件下会出问题初始化一下省事。分支名的选择。默认是master但有些平台新仓库默认分支改成了main。这个分支名要记牢因为 PicGo 插件配置里要填填错了就是 404。我一般统一用master减少变量。3.2 生成访问令牌比密码更安全的凭证PicGo 要往你的仓库提交文件就需要有权限。直接填账号密码既不安全也越来越不被支持正确做法是生成一个私人令牌Token。在平台的设置里找到令牌管理新建一个令牌。生成时会给一堆权限选项这里有个关键点权限要给够但别给多。图床只需要对仓库内容有读写权限具体来说勾选仓库相关的读写权限就够了不需要勾账号、勾组织管理等无关权限。权限给多了万一令牌泄露损失面更大。令牌生成后只会显示一次一定要当场复制保存好。我一般存到本地的密码管理工具里别直接写在某个 txt 里随手放桌面。这个令牌就是 PicGo 配置里的密码泄露了别人就能往你仓库里传东西。注意令牌不要提交到任何公开仓库也不要在截图里露出。我见过有人把配置截图发到社区求助令牌明晃晃在上面等于把仓库钥匙公开了。3.3 规划仓库目录结构为长期维护留后路很多人图省事所有图片都传到仓库根目录结果几百张图堆在一起找也不是、删也不是。我建议一开始就规划好目录比如按年月分images/ 2024/ 01/ 02/ 2025/ 01/PicGo 插件一般支持配置存储路径可以填固定路径也可以用日期变量自动生成。用日期分目录的好处是图片多了不会挤在一个目录里将来要清理旧图也方便按时间批量处理。这个习惯一开始养成后面省很多事。另外图片命名也值得说一句。PicGo 默认会用时间戳命名比如20240115143022.png好处是不会重名坏处是完全看不出内容。如果你在意可读性可以在插件里配置命名规则但要注意必须保证唯一性否则同名文件会互相覆盖。我的建议是保留时间戳命名可读性靠 Markdown 里的上下文来补别为了好看牺牲唯一性。4. PicGo 与 Gitee 插件的配置细节4.1 安装 PicGo 和插件的正确姿势PicGo 去官方发布页下载对应系统的安装包即可。装完之后先别急着配 Gitee先确认 PicGo 能正常启动、能看到主界面。然后进插件设置搜索 Gitee 相关的上传插件安装。这里有个高频坑插件安装失败或者装完不显示。原因通常是网络问题导致插件市场加载不出来或者 PicGo 版本太老不兼容新插件。我的处理顺序是先确认 PicGo 是最新版再确认网络能正常访问插件源如果还不行就手动下载插件包安装。手动安装稍微麻烦点但能绕过网络问题。插件装好后在 PicGo 的图床设置里会出现 Gitee 的配置项。如果没出现重启一下 PicGo还不行就是插件没装成功。4.2 配置项逐个填每个字段背后的含义Gitee 插件的配置项不多但每一项填错都会导致上传失败。我按重要程度逐个说。仓库地址repo格式是用户名/仓库名比如yourname/images。注意这里不要带完整的 https 前缀很多插件只认用户名/仓库名这种短格式填了完整 URL 反而报错。这是新手最容易填错的一项。分支branch填仓库的默认分支名前面说的master或main。填错就是 404。令牌token粘贴前面生成的私人令牌。注意前后不要有多余空格复制粘贴时很容易带上。存储路径path图片存在仓库的哪个目录下。可以留空表示根目录也可以填images/这种。如果插件支持日期变量可以填成带日期的格式实现自动按时间分目录。自定义域名customPath / customUrl这一项决定了 Markdown 里写入的图片 URL 长什么样。留空的话用平台默认的原始文件链接。如果你有自己的域名或者想用 CDN可以在这里配置。对大多数人来说留空即可。配置完记得点设为默认图床否则 PicGo 可能不知道用哪个图床上传。然后点确定保存。4.3 先手动测一张图别急着接 Typora配置完直接去 Typora 里试出问题你都不知道是哪一环。正确做法是先在 PicGo 里手动上传一张图测试。在 PicGo 的上传区拖一张图片进去看它能不能成功上传上传后能不能在相册里看到复制出来的链接能不能在浏览器里打开。这四步全过了说明 PicGo 到 Gitee 这条链路是通的再去接 Typora。如果这一步就失败看 PicGo 的日志。日志里会明确告诉你失败原因常见的有401或403令牌不对或权限不够。404仓库地址、分支名或路径填错。超时网络问题或者图片太大。上传成功但链接打不开多半是防盗链或者仓库是私有的。把日志看明白比盲目改配置高效得多。我每次帮人排查第一步都是让他把 PicGo 日志贴出来基本一眼就能定位。5. 把 Typora 接进来让截图自动变成链接5.1 Typora 图像设置的三个关键开关打开 Typora 的偏好设置 → 图像这里有几个开关要设置对。第一个是插入图片时的行为。选择上传图片这样粘贴或插入图片时 Typora 会触发上传。如果选成复制到指定路径图片就存本地了不会上传。第二个是上传服务的配置。Typora 支持直接选 PicGo选上之后它会自动去调 PicGo 的本地接口。如果列表里没有 PicGo 选项就选自定义命令手动填 PicGo 的命令行路径。用 PicGo GUI 的话一般直接选 PicGo 就行。第三个是上传成功后的格式。确认勾选对本地位置的图片应用上述规则和对网络位置的图片应用上述规则这样无论图片来自哪里都会走上传流程。设置完可以点 Typora 提供的验证图片上传选项按钮它会传一张测试图成功的话会提示你。这个验证功能很实用能快速确认 Typora 和 PicGo 是否打通。5.2 上传时机手动还是自动各有取舍Typora 支持两种上传时机手动上传右键图片选上传和自动上传插入即上传。两者各有场景。自动上传的好处是省心截图粘贴进去立刻变成链接写作过程无感。坏处是每张图都会立刻传到仓库如果你只是临时截个图试试也会被传上去时间长了仓库里一堆废图。而且自动上传对网络稳定性要求高网络不好时粘贴图片会卡一下。手动上传的好处是可控你确认这张图要用了再传。坏处是容易忘写着写着忘了传最后发布出去发现图是本地路径。我的习惯是写作阶段用自动上传但定期清理仓库废图。因为写作时频繁手动上传太打断思路而废图清理可以攒一批一起做。如果你对仓库整洁度要求极高那就用手动上传配合发布前的检查。5.3 验证整条链路从截图到链接的完整走一遍配置完成后做一次完整的端到端验证。新建一个 Markdown 文件截图后直接粘贴进去观察图片是否短暂显示上传中。上传完成后图片路径是否变成了https://...开头的链接。把链接复制到浏览器能否正常打开图片。把 Markdown 文件发给另一台设备打开图片能否显示。这四步都通过说明整条链路没问题。任何一步失败回到对应环节排查第 1 步失败看 Typora 设置第 2 步失败看 PicGo 日志第 3 步失败看仓库权限和防盗链第 4 步失败多半是链接本身有问题或者网络环境差异。6. 那些配置文档不会告诉你的坑6.1 防盗链图片在别人网站上打不开的元凶这是仓库图床最经典的坑。你在自己浏览器里打开图片链接好好的但把文章发到别的平台图片全部裂开。原因通常是平台对原始文件链接做了 referer 校验只允许来自本站的请求访问其他来源一律拒绝。这个问题的本质是你借用的文件服务默认是给浏览仓库这个场景用的不是给当图床外链用的。所以它限制外站引用是合理的。应对办法有几个。一是用平台提供的、明确允许外链的链接格式如果有的话。二是给图片链接加?参数绕过某些简单校验不总是有效。三是干脆换方案用专门的对象存储。我的经验是如果只是自己看、自己博客用防盗链一般不影响如果要到处分发仓库图床迟早会遇到这个问题这时候就该考虑升级方案了。6.2 图片体积为什么你的长截图传不上去平台对单文件大小有限制具体数值各平台不同但普遍不大。手机截的长图、高清设计稿很容易超过限制上传直接失败。解决办法是上传前压缩。PicGo 支持安装压缩插件可以在上传前自动压缩图片。压缩插件一般能配置压缩质量我通常设成 80% 左右肉眼几乎看不出差别体积能降一大半。对于截图这种内容压缩效果尤其明显因为截图里大片纯色区域压缩率很高。提示压缩是有损的如果是需要保留细节的图比如带小字的截图压缩质量别设太低否则字会糊。我一般对文字类截图设 90%对照片类设 75%。6.3 插件版本与 PicGo 版本的兼容问题前面提过插件报错很多时候是版本不匹配。具体表现是插件能装上但上传时报一些莫名其妙的错比如找不到某个方法、参数解析失败。排查方法先看 PicGo 的版本号再看插件的版本号去插件的发布页看它支持的 PicGo 版本范围。如果对不上要么升级 PicGo要么降级插件。别硬扛版本问题靠改配置是解决不了的。还有一个隐蔽的坑PicGo 升级后插件失效。有时候 PicGo 自动更新了旧插件不兼容新版本上传突然就挂了。所以如果你用的是稳定方案建议关掉 PicGo 的自动更新手动控制升级时机避免写作写到一半工具挂了。6.4 令牌过期与权限变更私人令牌可能有过期时间也可能因为你改了权限而失效。表现是原本好好的上传突然报 401。这时候别怀疑配置先去检查令牌状态重新生成一个换上。另外如果你在平台上改了账号安全设置比如开启了某种二次验证有时候会影响令牌的有效性。遇到突然的权限问题优先排查令牌。7. 让这套方案更耐用的几个习惯7.1 图片备份别把仓库当唯一存储仓库图床最大的风险是平台侧变化导致图片不可访问。所以本地一定要留一份图片备份。我的做法是让 PicGo 上传时同时保留本地副本或者定期把仓库里的图片目录拉下来存一份。这样即使哪天链接失效了图片还在换个图床重新传一遍就行不至于内容全丢。备份这件事平时感觉多余出事的时候能救命。我见过有人写了两年的博客图床一挂所有文章配图全没了那种崩溃是实打实的。7.2 定期清理仓库不是垃圾桶自动上传用久了仓库里会积累大量测试图、废图。定期清理一下既省容量又便于管理。清理时注意删图前先确认没有文章在引用它否则删完文章里就是裂图。可以用搜索功能在本地笔记里搜图片文件名确认没引用再删。7.3 方案的可迁移性别把自己锁死仓库图床方案的一个隐患是迁移成本。如果哪天要换图床所有图片链接都得改。降低这个成本的办法是图片命名和目录结构保持规范这样迁移时能批量处理。另外Markdown 里尽量用统一的链接格式别一会儿这个域名一会儿那个域名迁移时正则替换也好写。如果你对稳定性要求高其实可以一步到位用对象存储配置稍复杂但省心。仓库图床适合起步阶段和个人使用等你的内容量上来了再考虑升级也不迟。关键是别在起步阶段就追求完美方案先用起来边用边优化这才是务实的做法。我在实际使用中最大的体会是这套方案的价值不在于免费而在于可控。图片存在自己的仓库里链接自己说了算比用公共图床踏实得多。但它终究是借用平台能力所以心态上要把它当成够用就好的方案重要内容做好备份剩下的交给时间。配置本身十分钟能搞定真正花时间的是养成好的使用习惯而习惯才是让这套方案长期跑下去的关键。