写博客这几年我换过好几轮图片管理方案最早是直接把图片放本地写完再手动传到服务器后来试过免费的图床服务用一阵子要么域名失效要么图片被删最惨的一次整篇文章的图全部裂掉后台数据还在就是看不见图。直到我把 PicGo 和 Gitee 配合 Typora 用起来才算真正把插入图片这件事做成了一条全自动流水线在 Typora 里粘贴截图图片自动上传到 Gitee 仓库Markdown 里自动替换成线上链接不用手动改任何路径发布到哪里图片都不会丢。这篇文章把我这一年多实际使用中的完整配置过程和踩坑记录整理出来给同样被图片问题折磨的博客写作者一个可以直接照抄的方案。1. 博客图床涉及的问题比你想的严重1.1 不搭图床之前的日常工作流有多痛大多数写 Markdown 的人最开始都经历过这个阶段截图直接粘贴进文档Typora 默认把图片存到本地的一个 assets 或类似文件夹文章写完拷贝到博客平台发布时图片却传不上去。有人选择手动一张张上传一篇带十几张截图的教程文章光传图就要花半小时有人把图片丢到聊天软件再下载到手机压缩再传回来画质糊了还浪费时间还有人把整个文章作为 HTML 直接粘贴图片用 base64 内嵌导致文章体积剧增。这些方案都有一个共同的本质问题图片的存放位置和文章的存放位置没有分离。文章可以被复制、被迁移、被同步但本地的图片路径是死的只要换一台电脑、换个编辑器、换个发布平台图片就找不到了。1.2 图床的核心机制就是让图片有独立且固定的在线地址所谓图床其实就是给你提供一张图片的固定 URL 地址这个地址可以随时被加载。只要图片传到了图床上你的 Markdown 里就只存这个地址无论文章移到哪里渲染页面时只要网络能访问这个 URL图片就会显示。我用过几类图床图床类型优点缺点免费公共图床注册即用、无需维护图片随时可能被清理、域名可能变更、访问速度不稳定对象存储 OSS/COS稳定、有 CDN有费用、需要备案域名才能绑定自定义域名配置门槛高代码托管平台仓库免费、稳定、国内访问快有仓库容量限制、需要自己管理适合博客图片场景最后我把重心放在了 Gitee 仓库方案上。它的优势很明显不需要额外花钱有免费仓库容量国内服务器访问速度快不用担心图片外链被墙。配合 PicGo 这个开源的图片上传工具粘贴图片自动上传、自动返回链接整个链路完全自动化。虽然代码仓库的主要用途不是图床但对大多数个人博客来说图片量根本用不完仓库配额这套组合是性价比最高的选择。2. 环境准备Gitee 仓库创建到协议生成的整套步骤在开始配置之前需要先把两条基础链路准备好一是 Gitee 上要有专门放图片的仓库二是本机要有 PicGo 和 Typora。这三个组件各自的作用分别是Gitee 负责存储图片并提供外链PicGo 负责把本地图片上传到 Gitee 并返回 URLTypora 负责在你粘贴图片时自动调用 PicGo。2.1 创建图片专用仓库登录 Gitee 后在首页右上角点击新建仓库填写仓库名称一般取 blog-images、my-image-hosting 这类一眼能看懂的名字。仓库必须设置为公开这是很多人第一次配置时忽略的致命点如果仓库是私有的图片地址虽然能生成但外部访问时没有权限博客页面根本加载不出来。公开仓库只能看到你的图片文件不会暴露其他敏感内容所以可以放心公开。仓库创建好之后进入仓库页面复制仓库地址备用。这里有个小细节仓库地址有两种格式一种是 https 开头的克隆地址一种是 SSH 格式。PicGo 的 Gitee 插件需要用到的 repo 字段格式是用户名/仓库名比如我的用户名是 demo_author仓库名是 blog-images那 repo 就填 demo_author/blog-images注意不要带 .git 后缀和 https:// 前缀。2.2 生成访问令牌Token图床插件往 Gitee 上传图片时需要用 Token 来通过 API 鉴权这个 Token 就相当于你 Gitee 账号给第三方应用颁发的一张通行证。生成路径在 Gitee 右上角头像菜单里打开设置——私人令牌页面会自动显示一段密码确认输入密码确认后点击生成新令牌。生成令牌时会给一个范围选择只需要勾选projects这个权限就可以满足上传文件的 API 调用需求。令牌生成后只会完整显示一次页面刷新后就不能再看到了所以要立刻复制保存到本地临时文件里。我建议在完成全部配置之前先不要关闭这个页面万一后面配置出错你可以当场重新生成不用再走一遍密码验证流程。2.3 安装 PicGo 和 Typora 的几个注意点PicGo 的下载页面在 GitHub 上可以找到它同时提供 Windows、macOS、Linux 三个平台的安装包Windows 下载 exe 安装包macOS 下载 dmg 文件。安装过程没什么特殊的一路下一步即可。但有一个容易忽略的点如果你之前用过旧版本的 PicGo升级新版之后最好清空一下配置文件再安装否则旧版本残留的配置可能和新版插件产生冲突表现为上传时报奇怪的错误。Typora 从官网下载对应系统的版本安装完成后先不用急着修改设置因为 PicGo 的图床配置和 Typora 的联动是两回事我们一步一步来。另外提一句PicGo 可以不用安装到默认目录但注意不要放进包含中文的路径里。虽然大多数情况下软件能正常运行但个别插件读取配置文件时遇到中文路径的兼容性偶尔会出幺蛾子你要是后续发现图片上传报配置文件读取失败之类的错误优先检查这一点。3. PicGo 的 Gitee 图床配置逐字段拆解PicGo 本身默认支持七牛、腾讯云、又拍云、GitHub 等图床Gitee 不在默认列表里需要先安装第三方插件。打开 PicGo 主界面的插件设置搜索 gitee会看到一个名为gitee-uploader的插件点击安装。安装完插件后左侧菜单会出现Gitee 图床的相关配置页。3.1 五个关键字段的理解进入配置页面会看到这几个输入项字段填写内容说明repo用户名/仓库名必须和 Gitee 仓库完全一致大小写不能错branchmasterGitee 默认分支是 master不是 main如果之前在仓库设置里改过默认分支这里改成实际分支名token私人令牌字符串刚才生成的令牌pathimg/图片存储在仓库中的目录路径留空则存在根目录customUrlhttps://gitee.com/用户名/仓库名/raw/master最终拼接图片地址的前缀格式很重要这里我需要重点解释 path 和 customUrl 的关系。path 决定图片文件放到仓库的哪个文件夹里customUrl 决定最终生成的图片外链地址。打个比方你上传一张叫 example.png 的图片path 设置为 img/那么图片在仓库中的路径就是 img/example.png。而 customUrl 必须指向这个文件所在的访问入口即仓库的 raw 访问地址加上仓库名和分支名最后拼接出来的完整 URL 就是customUrl path 图片文件名。很多人配置失败就是因为在 customUrl 里加了 path 目录又在 path 里重复填了目录最后生成了双重路径图片全部 404。正确做法是 customUrl 只填到 master 为止目录统一交给 path 字段管理。3.2 图片命名规则的正确选择PicGo 的 Gitee 插件支持几种文件名格式我建议选择时间戳命名法比如2025-06-14-14-35-22.png或者带随机数。选这种命名有实际原因如果你重复上传同一张图片旧文件会被覆盖导致历史文章中引用的图片内容悄悄被替换这个问题非常隐蔽。用时间戳随机数命名每次上传都是新文件从根源上规避了文件名冲突。自定义前缀这里也可以填一个简单的标识比如 不填或者按博主名区分。我用的是blog前缀这样在仓库里一眼就能看出哪些图是博客文章用的。3.3 先用上传按钮验证配置是否正确配置完成后别直接去 Typora 那边测试先在 PicGo 的上传区随便拖一张图进去点击上传。如果返回的 URL 能直接在浏览器里打开并看到图片说明 plugin 配置成功。这一步通过后再去配置 Typora能省去大量排查时间。原则就是让问题停留在最小范围内先确认上传组件没问题再确认联动组件没问题。4. Typora 和 PicGo 联动两分钟完成自动上传Typora 的优势在于它对 Markdown 图片处理的深度整合不需要任何第三方脚本只要在偏好设置里指定上传服务后续所有粘贴的图片都会自动走这个流程。4.1 Typora 图像设置面板的入口打开 Typora 的偏好设置界面找到图像选项卡这里会看到关于插入图片时的一系列选项。核心设置如下插入图片时选择上传图片上传图片服务选择PicGo.appmacOS/ PicGoWindowsPicGo 路径选择 PicGo 安装目录下的可执行文件这里有个隐藏细节Typora 识别 PicGo 是通过调用 PicGo 的启动程序来触发的不是通过复制粘贴 API。路径填错、或者填的是 PicGo 的快捷方式路径都会导致 Typora 左下角短暂闪现一条错误但图片没上传成功。Windows 下正确路径通常是C:\Program Files\PicGo\PicGo.exe或你自定义安装位置的完整 exe 路径。4.2 为什么不推荐自定义命令方式Typora 的图像配置里还有一个自定义命令选项允许你填一条命令行脚本来自行处理图片上传。一些博客教程推荐这种方式但我的实际体验是自定义命令的维护成本高出不少你得自己处理图片的接收参数、格式化上传结果、输出链接脚本稍微写得不符合 Typora 对输出格式的预期就会静默失败。相比之下走 PicGo 应用的方式Typora 自动把图片路径传给正在运行的 PicGo上传完成后 PicGo 把链接回传给 Typora 自动写入文档这种官方维护好的交互协议比你自己写的 shell 脚本可靠得多。4.3 实际验证粘贴一张截图看全链路配置完成后随便截一张图在 Typora 里按 CtrlV 粘贴。Typora 右下角会显示一个上传中的提示一两秒后图片正常显示在编辑区。这时候右键点击图片选择图像——复制图像地址复制出来的一长串 URL 应该是指向 Gitee 仓库的。把这个地址浏览器打开检查一下能看到图片且地址中的路径结构与我们在 PicGo 里配置的路径拼接一致说明全链路已经跑通。验证时要特别留意图片的显示状态如果粘贴后图片短暂显示一下又变成裂图十有八九是上传后返回的 URL 有问题先回到 PicGo 的相册里查看历史上传记录看 PicGo 最终上传成功后显示的 URL 是什么。通过这个中间日志能快速定位是上传环节的问题还是 Typora 接收链接的问题。5. 上传失败的排查手册我踩过的每一个坑这套方案整体稳定但初次配置时失败的环节很集中。我把这一年多遇到过的问题按频率排序整理成一张排查表再逐个详细说。现象最常见原因解决方向上传成功但 404customUrl 拼接错误或仓库私有检查 URL 路径与仓库实际内容上传超时或失败token 权限不够或已过期重新生成并勾选 projects 权限图片插入后是空链接Typora 没正确调用 PicGo检查 PicGo 路径设置上传同名文件不更新文件重名且插件未开启覆盖改用时间戳命名5.1 上传成功但浏览器打开 404这是配置阶段最常遇到的情况。PicGo 显示上传成功说明文件确实进了仓库404 只可能是访问地址不对。先从 PicGo 复制上传成功的 URL和浏览器里实际打开的对比手动核对每一段路径。检查顺序如下URL 开头是否指向gitee.com/用户名/仓库名/raw/master这个格式。很多人从仓库页面复制的是仓库主页地址拼出来的 URL 打开的是网页而不是图片。确认仓库确实是公开状态。在 Gitee 仓库页面右上角可以看到仓库可见性如果显示私有任何外链都会 403 或 404。确认分支名。PicGo 填了 master但仓库默认分支改成 main上传虽然会成功raw 链接却指向不存在的路径也会 404。这个错我犯过两次每次都是因为换了仓库忘了检查分支。5.2 Token 权限不够导致的上传失败PicGo 报错信息有时能直接看到403 Forbidden有时只是显示上传失败。遇到这种情况先把 token 页面打开确认生成时是否勾选了projects。很多人会误以为勾选所有权限更保险但某些插件在获取过大的权限列表时反而会因为 Gitee 的接口校验顺序出错。实际测试下来只勾projects是最干净的方案。还有一种隐蔽情况Gitee 的个人令牌如果长期不用不会失效但如果你修改了 Gitee 密码之前生成的令牌会被直接重置。所以如果你某天突然发现 PicGo 全部上传失败而之前一直正常优先怀疑是不是改了密码导致的 token 失效。5.3 照片能上传但 Typora 文档里图片是空的这类问题的特征很典型PicGo 的相册里能看到上传记录但 Typora 文档里插进去的图片位置是一个灰色占位块甚至没有链接。大概率是 Typora 调用 PicGo 的方式有问题。Windows 上最常见的原因是填写的 PicGo 路径带有空格并且没有去掉多余的空格Typora 无法启动程序macOS 上则可能是直接填了 .app 而不是 .app/Contents/MacOS/PicGo。Mac 用户需要特别注意Typora 调用的是可执行文件不是应用程序包路径要精确到二进制文件层。5.4 同名图片反复上传后文章引用的图片被换掉这个问题不是报错而是逻辑错误。当你用固定文件名重复上传时PicGo 不会生成新文件而是覆盖旧文件Gitee 上该文件的更新时间变新但 URL 不变。单次使用时没问题坏处在于如果两个不同文章都引用了这张图片你往这个文件名重新上传了另一张图那么两篇文章里的图片都被替换了。表现在博客上就是某天开始旧文章里的配图莫名其妙变成了另一张图。所以我在前面章节强烈建议用时间戳命名就是在这里踩过坑后的教训。5.5 链路分层定位法问题到底出在哪一环如果上传失败且无法一眼定位我习惯按Typora——PicGo——Gitee三层逐步隔离。先在 PicGo 里手动上传一张图片如果成功说明 PicGo 到 Gitee 这一段没问题再检查 Typora 粘贴图片时 PicGo 的日志窗口有没有动作如果 PicGo 完全没反应说明 Typora 到 PicGo 这一段断了如果 PicGo 日志有报错说明问题在 PicGo 到 Gitee 这一段。这套方法几乎能覆盖所有故障点比盲目翻配置文件高效得多。6. 长期使用下来的实测心得和存储策略建议这套方案用了稳定后我基本告别了图片困扰。但能用和好用之间还有几层优化空间我根据自己的使用习惯沉淀了几条实用经验。6.1 仓库目录按日期分层的规划如果你只是偶尔写文章图片全丢在根目录问题不大。但文章数量上百之后根目录几百张图片会很难打理Git 客户端里看仓库也特别吃力。我现在的做法是 path 填img/2025/06/这种按年和月分层的路径。PicGo 是支持 path 中包含多级目录的。这样每当写出文章时图片能顺着月份归档需要清理或备份时也很直观。有朋友问我为什么不按文章来分目录我觉得按月分更省心——文章的分类和发布时间经常变动按文章分目录的话换分类时图片路径也要跟着改太麻烦了。6.2 图片压缩别让几张截图吃满仓库配额Gitee 虽然免费但单个仓库的大小是有上限的。截图动不动单张 2MB几十篇文章就能积累几百 MB。建议在截图或导出图片时就做压缩。Typora 本身不对图片做处理所以我在 Windows 上用截图工具自带的分辨率缩放或者在上传前用一个轻量压缩脚本走一遍。压缩目标是单张图片控制在 200KB 以内博客文章阅读体验完全不受影响但仓库空间消耗减少十倍。6.3 仓库图片备份的必要性任何免费服务都不能保证长期不变。代码托管平台的定位毕竟是存代码图片外链理论上也存在被清理或政策调整的可能。我的应对方案是定期把仓库的 images 目录 git clone 到本地压缩存档放入网盘。这个过程一个月一次成本很低但万一图床不能用至少手里有完整的图片原稿可以迁移到其他平台。6.4 Typora 的其他图床备选方案虽然本文讲的是 Gitee但如果你遇到了必须迁移的情况PicGo 的插件生态里有现成的 GitHub 图床插件配置逻辑几乎一样只是把 repo 地址换成 GitHub 的customUrl 换成 GitHub raw 域名。另外一些国内知名对象存储平台也提供了官方的 PicGo 插件适合对图床稳定性要求更高的场景。Gitee 方案最大的意义是零成本、零门槛等你图片量真正大到需要上对象存储的时候再迁移也不迟。最后分享一个实用小技巧PicGo 有一个相册功能可以查看所有历史上传图片但当相册积累太多记录时PicGo 启动会变慢可以在设置里定期清空历史记录这个操作不会删掉仓库里的图片只是清理软件本地的记录列表不用担心。