做技术写作、喜欢用 Markdown 记录东西的人应该都有过这种经历文章写到一半随手插一张截图本地预览看着挺正常结果发布到博客或者群文件里图片就变成一片空白或者一个裂开的图标。原因也很简单——图片存的还是你电脑上的本地路径换一台设备就彻底找不到了。今天要聊的这个组合TyporaPicGoGitee就是为了彻底干掉这个麻烦。这套方案解决的核心问题有两个一是把本地图片自动变成远端可访问的链接二是让整个写作环境保持“本地编辑、云端存储、随时发布”的顺畅体验。你可以用它写博客、写文档、做学习笔记也可以把它绑定到静态博客比如某博客框架上实现写完直接上传的流程。下面我会从选型思路、环境配置、图床搭建到常见问题排查完整走一遍。1. 整体思路与方案选型先说我自己的经历。以前我偷懒图片直接放本地文件夹文章发去某个平台时先把文字复制过去再一张张手动传图、调整位置一篇文章光配图就得花十几分钟。后来改用网盘外链结果外链时不时失效图说没就没体验很差。再后来接触到图床的概念才知道“图片外链”这件事本身就该交给专用工具处理。1.1 三个工具各自的定位先亮出这套组合的完整链路Typora 负责本地写作它是一款所见即所得的 Markdown 编辑器写的时候左侧是源码右侧是渲染效果粘贴图片、表格、代码块都直接显示不用靠想象排版。PicGo 负责图片上传它是一个桌面端的图床管理工具可以配置不同的图床服务比如 Gitee、某云存储、某云存储等支持拖拽上传、剪切板上传还自带相册管理图片传上去之后自动返回外链地址。Gitee 负责图片托管这里把 Gitee 当作一个免费的图床服务来用。它本质是一个代码托管平台但我们用它的仓库来存放图片文件再通过 raw 链接直接访问图片。三者配合起来的工作流是这样的在 Typora 里粘贴或拖入一张图片编辑器自动调用 PicGoPicGo 把图片上传到 Gitee 仓库然后把可访问的图片外链回填到 Markdown 文档里。整个过程你看到的就是“我粘贴了一张图它在文档里显示出来了”实际上背后已经把图片送上了云端。1.2 为什么选 Gitee 而不是 GitHub很多教程推荐用 GitHub 做图床理由是免费、稳定、全球可访问。但如果你人在国内GitHub 的图片外链加载速度时快时慢尤其是文章里图片多了之后体验会很差有时候甚至完全打不开。Gitee 在国内访问速度相对稳定而且对个人开发者免费仓库数量也没有硬性限制拿来放图片绰绰有余。当然 Gitee 也有它的短板平台对图片内容有审核机制如果图片涉及违规内容外链可能被删除仓库大小也有上限不能无限制堆图片。但就正常图床用途比如博客配图、文档插图、学习笔记里的截图这些使用场景完全能够满足。1.3 与其他方案对比为了让你更直观地理解这个组合的位置用一张表格对比几种常见方案方案优点缺点适合场景本地图片无需联网编辑快不能跨设备发布需手动处理本地笔记、临时文档网盘外链容量大操作简单外链易失效部分平台防盗链偶尔分享文件云存储图床稳定、有 CDN、可自定义域名需实名认证可能收费正式博客、商业项目GitHub 图床免费、开发友好国内访问不稳定容量有限面向海外用户的站点Gitee 图床国内访问快、免费有审核机制仓库大小受限中文博客、个人写作从这个对比能看出来Gitee 图床的定位很明确它不是一个“最好”的方案但它是“国内用户、零成本、上手快”这几个条件下最均衡的选择。如果你将来文章量大了、图片多了再迁到云存储图床PicGo 里改个配置就行前面的写作流程不受影响。2. 环境准备与 Typora 基础配置搭建这个写作环境之前先把基础软件准备好。2.1 下载安装三个工具Typora 官网下载对应 Windows/macOS/Linux 版本安装时按默认路径就好。PicGo 官网下载对应系统版本客户端Windows 用户建议下载安装版Setup 后缀macOS 用户下载 dmg 包。如果电脑里还没有 Git 工具也顺手装一个后面从 Gitee 克隆仓库备份图片时需要用到。安装过程中没有特别需要注意的坑唯一要提醒的是PicGo 装完之后最好先打开一次让它生成默认配置目录否则后面 Typora 调用时找不到配置文件容易莫名报错。2.2 Typora 核心偏好设置Typora 安装完成后先别急着写文章花两分钟把偏好设置调整好。打开菜单栏的“文件 → 偏好设置”重点关注以下几项第一通用设置里可以打开“自动保存”相关的选项如果你的版本里没有这个选项问题也不大编辑器本身在崩溃恢复方面做得还不错。第二外观设置里可以调整主题和字体。Typora 自带几套主题比如 Github、Newsprint 等我平时用的是 Github 主题代码块颜色对比度高看起来舒服。如果你想更个性化也可以在主题文件夹里放自定义 CSS。第三图像设置是一会儿要重点配置的地方这里先略过第五章会详细展开。第四在“编辑器”设置里建议开启“代码块自动换行”和“显示行号”对长文档编辑更友好。关于 Typora 的免费和付费版本问题如果你下载的是较新版本软件已经转为付费授权买一次可以长期使用如果不想付费也有免费版可用功能上对写作影响不大。这个你自己权衡但我个人觉得它值这个价毕竟日常写作天天用。2.3 创建本地工作目录建议为博客写作单独建一个文件夹比如 D:\blog里面按时间或者按主题分子目录。Typora 支持打开整个文件夹相当于一个工作区左侧能看到目录树写作时切换不同文章很方便。工作目录建好之后把写作相关的图片也规划好。图床模式下图片自动上传云端本地可以不保留图片副本但如果你对稳定性有要求建议开启 Typora 的一个功能在图像设置里勾选“拷贝图片到相对路径下”这样本地会留一份原始图片云端也存一份双保险。这一步很多人会忽略但等到图床那边偶尔出问题这份本地备份就能让你从容应对。3. Gitee 图床搭建这是整篇文章的核心环节Gitee 仓库的配置直接决定后面的上传、访问是否顺畅。3.1 注册并创建仓库先去 Gitee 官网注册一个账号用邮箱或手机号都行。注册完成后登录进入右上角“”图标选择“新建仓库”。仓库名称建议用英文或拼音比如 blog-images、pic-bed不要用中文原因后面会讲。仓库路径会自动关联用户名和仓库名这个会体现在图片外链 URL 里所以选一个简短好记的名字。默认分支建议保持 master 或者 main 都行后续 PicGo 配置里要填保持一致即可。“是否开源”这里选公开。图床的本质是公开可访问的图片资源如果你选了私有图片外链大概率无法访问或者访问时需要额外授权这就失去了图床的意义。“初始化仓库”建议勾选“使用 Readme 文件初始化”这样仓库创建后不是空的方便后续测试。3.2 生成私人令牌PicGo 上传图片到 Gitee 仓库不是靠账号密码而是靠私人令牌Token。相当于给第三方工具开了一把专用的钥匙钥匙的权限可以限制即使泄露也只是影响这个图片仓库不至于影响整个账号。生成令牌的路径登录 Gitee点击头像 → 设置 → 私人令牌进到这个页面后会看到当前已有的令牌列表点击“生成新令牌”。令牌描述随便写比如“picgo-blog-images”。权限选择上只需要勾选“projects”里的 Projects 即可其他权限一律不勾。这里重点解释一下图床上传需要的就是往仓库里写文件的权限“projects”这个权限足以完成推送操作选更多权限等于把整个账号的安全交出去没必要。生成之后页面会显示一串形如随机字母数字组合的令牌值这个值只会完整显示这一次务必立刻复制保存到本地文本文件里。如果关闭页面后再想看只能重新生成新的令牌。3.3 仓库名与令牌的关联逻辑这里有个概念要理清楚Gitee 图片外链的 URL 结构是固定的——https://gitee.com/{用户名}/{仓库名}/raw/{分支名}/{图片路径}比如用户名是 alice仓库名是 blog-images分支是 master图片存放在 img 目录下外链就是https://gitee.com/alice/blog-images/raw/master/img/example.png注意路径里的关键词是 raw不是 blob这是很多人配置完图床后图片打不开的第一大坑。Gitee 的页面浏览地址通常是 blob比如 https://gitee.com/alice/blog-images/blob/master/img/example.png这个地址打开是一张页面而不是图片本身。但博客写作时需要的是指向图片文件的原始链接所以必须用 raw。这个 URL 结构理解之后你后面配置 PicGo、排查问题都会清晰很多。4. PicGo 图床客户端配置Gitee 的仓库和令牌准备好之后下面把焦点转到 PicGo 上。4.1 安装 Gitee 图床插件很多人装完 PicGo 后发现设置里只有默认的图床选项像某云存储、某云存储等找不到 Gitee。原因很简单Gitee 不是 PicGo 内置的图床类型需要手动安装插件。打开 PicGo 主界面进入“插件设置”在搜索框里输入 gitee-uploader找到对应插件安装。安装完成后一般需要重启 PicGo 才能生效。插件安装过程可能出现失败的情况常见原因是网络波动或者安装源不稳定。如果装不上换一个网络环境再试或者多试几次通常都能装成功。这里不用太担心后续配置才是重头戏。4.2 配置 Gitee 图床参数重启 PicGo 之后在左侧导航栏找“图床设置”如果插件安装成功这里会出现一个“Gitee”选项点开后需要填写几项参数参数名填写内容说明ownerGitee 用户名注册时使用的用户名repo仓库名称创建仓库时填写的那一个token私人令牌3.2 节生成的钥匙branch仓库分支名master 或 main与创建时一致path图片存储路径比如 img会自动创建该目录message提交信息上传图片时自动生成的提交说明customUrl自定义域名没有域名就留空不用管每一项填完后都要保存。这里要特别强调 path 参数的作用它决定了图片上传到仓库后存放在哪个子目录下。如果仓库里图片比较多建议按月或者按主题建目录比如 img/2025/01 这样后期管理起来清爽很多。至于插件界面里的其他参数不同版本可能略有差异以你安装的版本为准。关键要理解每个字段对应的是仓库里的哪个位置只要理解了这个界面怎么变都能应对。4.3 上传测试配置完后切换到 PicGo 的“上传区”拖动一张测试图片到上传区域或者直接粘贴截图。如果配置正确上传区会显示上传进度随后返回一个 URL。复制这个 URL 到浏览器打开如果能正常显示图片说明图床链路已经通了。如果上传报错根据提示信息排查方向提示认证失败或 401令牌不对或者权限不足回 3.2 节重新生成令牌提示仓库不存在owner 或 repo 填错注意仓库名是创建仓库时填的那一个和路径中的大小写要保持一致提示分支不存在branch 填错登录 Gitee 页面确认默认分支是 master 还是 main上传成功但 URL 打不开检查 URL 用的是不是 raw 而不是 blob以及 owner 和 repo 是否正确第一次跑通这个流程大概需要 10 分钟。跑通之后整个写作环境的难点基本就全部拿下了。4.4 关于自定义域名的补充如果你有自己的域名并配置了 CNAME 指向 Gitee或者将来准备迁移到云存储可以在 PicGo 里设置 customUrl。这个参数的原理是替换返回链接中的域名部分。举个例子默认外链是 https://gitee.com/alice/blog-images/raw/master/img/a.png如果设置 customUrl 为 https://cdn.example.com那返回链接就变成 https://cdn.example.com/blog-images/raw/master/img/a.png。但要注意这要求你确实把这个路径映射到了对应的资源。对新手来说没有域名就先不要填不要画蛇添足导致链接反而打不开。5. Typora 与 PicGo 联动配置Gitee 仓库、PicGo 客户端都准备好了最后一步是把 Typora 的图片上传动作和 PicGo 对接起来。5.1 Typora 图像设置打开 Typora 偏好设置 → 图像这里是整个联动配置的入口设置项不多但每一项都要理解清楚。“插入图片时”这里选择“上传图片”。 “上传图片服务”选择“PicGo(app)”。设置完成后下方会出现一个路径输入框点击“PicGo 路径”后的文件夹图标选择你安装 PicGo 的程序文件路径。Windows 下通常是安装目录里的 PicGo.exe。同时把下面两个选项也勾上“对本地位置的图片应用上述规则”意思是如果文档里有本地图片上传时一并处理。“对于网络图片应用上述规则”意思是直接把外链图片传给 PicGo 重新上传避免原链接失效。这两个选项建议都勾上尤其在写文章时经常从网上复制参考资料截图勾上后就不用手动一张张转换了。5.2 用一张图验证整个流程配置完成后打开一个新文档直接 CtrlV 粘贴一张截图。Typora 会弹出一个上传动画几秒后图片出现在文档里此时可以在图片上右键 → 图像 → 复制图片链接看链接指向的是否为 Gitee 仓库地址。如果链接是 https://gitee.com/... 开头说明整个链路已经打通。如果链接还是本地路径或者复制出来看起来不对需要回到上几步检查配置。这里有个容易被忽略的点Typora 在调用 PicGo 时默认走的是本地端口 36677。如果你电脑上有别的程序占用这个端口或者 PicGo 设置了代理可能导致调用失败。PicGo 的设置里可以修改监听端口修改后 Typora 不用重新配置因为 Typora 调用的是 PicGo 提供的服务端口变了会自动发现。5.3 粘贴、拖拽、插入三种上传姿势Typora 支持多种方式插入图片它们在上传行为上略有区别粘贴CtrlV / CmdV最常见截图后直接粘贴图片自动上传。拖拽从文件管理器把图片拖进 Typora 窗口同样会触发上传。“格式 → 图像 → 插入本地图片”手动选择文件适合已经存在本地文件系统里的大量图片。三种方式都能触发上传逻辑但粘贴和拖拽属于实时操作上传失败时会立刻看出来插入本地图片时如果本地图片路径不在工作目录下Typora 会更明显地提示是否要复制到当前目录这时候按提示操作即可。5.4 多图场景批量处理文章配图多的时候比如一篇教程配 20 张截图不需要一张张粘贴。先把所有截图放到一个临时文件夹然后一次性“插入本地图片”选中多张Typora 会逐张上传。批量上传时PicGo 对并发上传数量有默认限制图片多的时候你可以看到上传区排队处理。实测下来30 张以内不会有太大问题再多的话建议分批处理否则偶尔会出现个别图片上传失败、需要手动重新上传的情况。批量导入会影响生产环境中的图片整理方式我的个人习惯是写作时随手粘贴插图不回看上传过程整篇文章写完之后去 PicGo 相册里检查一遍是否有失败记录有失败的重新上传没有就继续。6. 写作流程优化与仓库维护图床搭好只是第一步真正顺手的使用体验来自日常的流程规范和仓库维护。6.1 一套完整的写作闭环现在完整的流程是这样的写作前新建 Markdown 文件写在本地工作目录里。写作中随时粘贴截图、插入本地图片Typora 自动上传并回填外链。写完后文章内容包含的图片已经全部是 Gitee 外链可以直接复制到博客后台、公众号编辑器或者其他任何支持 Markdown 的平台。假如你用某种静态博客框架还可以把文章文件推送至远端仓库实现发布。这套流程最大的价值在于写作本身不被打断。你不需要停下来考虑图片放在哪里、上传去哪里、链接怎么写这些杂事都由工具消化掉了。6.2 本地图片备份策略刚才提到了本地双备份这里展开说明一下。Typora 的图像设置里如果勾选了“优先使用相对路径”并且开启了本地副本那么每张上传成功的图片都会在文章所在目录下留一份副本。这带来的好处是即使某天图床异常或者外链失效本地文件还在重建链接只是时间问题。我的习惯是每周手动把工作目录里的图片文件夹通过 Git 推送一次到另一个私有仓库作为归档备份。这样即便本地磁盘损坏历史图片也有恢复途径。6.3 Gitee 仓库的容量和流量管理Gitee 单仓库大小有限制具体数值不同时期会有调整但核心思想是别把它当无穷无尽的资源用。写文章中产生的截图单张通常几十 KB一篇带图教程大概 1-3 MB即使一个月写 20 篇一年下来也就几百 MB完全可控。真正要注意的是不要往仓库里传视频、压缩包、大文件那不是图床该管的事。如果确实遇到仓库过大的情况按年份拆分仓库比如 blog-images-2025、blog-images-2026PicGo 里改 repo 字段就可以切换。6.4 多设备同步的方案如果你在台式机和笔记本之间轮流写作图床解决了图片跨设备访问问题但 Markdown 文件本身的同步还需要另外的方案。可以选择任一网盘同步工具把工作目录自动同步到多台设备或者用 Git 仓库保存文章源文件。我自己用的是 Git 私有仓库 网盘双同步文章源文件推送到私有仓库同时网盘目录里实时备份保证哪台设备出问题都能恢复。7. 常见问题与排查技巧实录这个环境搭完之后大概率不会一直一帆风顺。我把自己和身边朋友踩过的坑整理成清单你遇到类似问题可以按图索骥。7.1 问题速查表常见问题的排查优先级如下现象可能原因排查与解决图片上传失败提示 401令牌错误或权限不足重新生成令牌确认勾选 Projects 权限上传失败提示 404仓库或分支不存在检查 owner/repo/branch确认大小写上传成功但图片打不开URL 用了 blob 而非 raw手动改成 raw 测试确认 PicGo 返回链接格式图片能打开但很模糊可能被平台压缩检查原图尺寸重新上传原图Typora 无法调用 PicGo端口冲突或软件路径错误检查 PicGo 是否运行端口映射是否正常图床上传后外链被删除图片内容违反平台规范确认图片内容合规关注平台通知仓库里出现奇怪目录结构path 配置错误检查 path 是否有前导/后缀重新上传某张图片上传后显示为裂图上传失败但回填了错误链接去 PicGo 相册查看失败项重新上传其中 404 和 401 出现的频率最高80% 的配置问题都出在这两类错误上。7.2 深入排查上传失败当 PicGo 上传失败时有一种比较隐蔽的情况插件版本和自己填写的参数不匹配。比如旧版插件可能没有经典那类参数只需要 owner、repo、token、path而新版插件要求填写 message 且不能为空。这种问题没有统一的标准答案最好的办法是看插件的文档或源码说明理解每个字段含义后再填写。还有一个容易踩的坑是仓库名的大小写。Gitee 仓库名如果创建时包含大写字母PicGo 里必须原样填写不能改成小写。链接也一样大小写不同服务器返回的可能不是同一个资源。7.3 图片上传成功但显示不出来的排查这类问题比上传失败更折磨人因为上传动作成功了图床文件也在但浏览器打不开或者页面显示裂图。优先检查 URL 前缀用浏览器访问返回的链接确认是不是 https://gitee.com/ 开头如果不是检查自定义域名相关配置。其次检查图片访问权限。虽然仓库是公开的但 Gitee 对部分地区的访问偶尔会有波动这时候等一等或者换网络再试。如果一直不行考虑改走云存储图床这也是为什么我在方案选型里建议预留迁移空间。7.4 关于 Gitee 平台审核机制Gitee 作为国内的代码托管平台对仓库内容的审核比海外平台严格。图床仓库如果出现非法、色情等违规图片平台可能会删除文件甚至冻结仓库。这个机制既是保护也是限制正常写作的截图、配图不会触发但如果你打算用它存放一些灰色领域的内容趁早换个思路。另外万一发现某张图片的外链在某天突然失效先去 Gitee 仓库页面看看文件是否还在。如果文件在但链接打不开大概率是网络波动如果文件已经不在了就是被平台清理了需要在本地备份里找回后另作处理。8. 这套方案还能怎么扩展前面讲的都是基础用法其实这套环境还可以往几个方向扩展让它发挥更大作用。8.1 接入个人静态博客现在很多技术博主用静态博客框架发布内容写完的 Markdown 文章直接推到托管平台触发自动构建。这个流程和我们的写作环境是天然兼容的Typora 负责写作和图片管理文章推送交给 Git图片链接已经固化在文章内容里发布时不需要任何额外处理。8.2 图片批量整理的进阶玩法PicGo 的相册功能不只是看看上传记录还支持删除图床中的图片。如果你写了多篇文章后想清理旧图可以在相册里筛选过期的图片做批量删除。这里提醒一句删除操作不可逆执行前先确认这张图片没有被历史文章引用否则链接会突然失效很影响阅读体验。8.3 迁移到云存储文章写到一定量后Gitee 图床的容量和访问稳定性可能成为瓶颈。此时可以平滑迁移到云存储服务流程并不复杂先开通云存储并创建 Bucket把 Gitee 仓库里的图片批量下载后重新传到 Bucket然后在 PicGo 里新增对应的图床源最后把旧文章里的链接批量替换成新的外链地址。这一整套操作在 PicGo 里都能完成不需要改动 Typora 的写作习惯这也是当初选 PicGo 的好处之一——它是一个中枢后面无论是换图床还是新增服务都不用重新配置编辑器。我个人在实际使用中的体会是这套环境的搭建大概需要半小时第一次用完你会觉得也就那么回事。但长期写作下来你会发现它帮你省下的时间和精力远超预期。偶尔图床出问题的时候也别急着骂工具先按上面的排查思路走一遍大多数问题都能在两分钟内定位。如果有一天你换了新电脑需要重新配置把私人令牌和仓库名两个关键信息找回来剩下的步骤照着这篇文章再来一遍就行。