1. 为什么写博客的人最后都会折腾图床这件事
如果你写 Markdown 笔记或者博客超过三个月，大概率会遇到一个很烦的问题：本地截图粘贴进去，图片路径是C:\Users\XXX\Pictures\screenshot.png这种。自己电脑上看着好好的，一旦把笔记同步到另一台设备、发给别人、或者发布到静态博客上，图片全部裂开。更别提用 Typora 写文章时，截图粘贴进去默认存到本地某个临时目录，时间一长自己都找不到图在哪。
解决这个问题的核心思路就一句话：让图片有一个公网可访问的 URL，Markdown 里只存这个 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 服务（默认端口 36677），Typora 就是通过这个本地接口把图片"喂"给 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 里尽量用统一的链接格式，别一会儿这个域名一会儿那个域名，迁移时正则替换也好写。
如果你对稳定性要求高，其实可以一步到位用对象存储，配置稍复杂但省心。仓库图床适合起步阶段和个人使用，等你的内容量上来了，再考虑升级也不迟。关键是别在起步阶段就追求完美方案，先用起来，边用边优化，这才是务实的做法。
我在实际使用中最大的体会是：这套方案的价值不在于"免费"，而在于"可控"。图片存在自己的仓库里，链接自己说了算，比用公共图床踏实得多。但它终究是借用平台能力，所以心态上要把它当成"够用就好"的方案，重要内容做好备份，剩下的交给时间。配置本身十分钟能搞定，真正花时间的是养成好的使用习惯，而习惯才是让这套方案长期跑下去的关键。
