如果你和我一样习惯用 Typora 写 Markdown 笔记那你一定遇到过这种尴尬文章里贴了十几张截图本地打开一切正常一旦复制到博客后台或者发给同事图片全部裂开。问题不在 Typora而在于 Markdown 里的图片引用本质是一个路径问题本地路径一旦离开本机就失效。Typora PicGo Gitee码云这套组合就是为了解决路径断裂而生Typora 负责写作PicGo 负责把图片传到 Gitee 仓库Gitee 返回一个公开可访问的图片直链Markdown 里引用这个直链文章放到任何平台都能正常显示。这套方案适合所有用 Markdown 写作的人——写技术博客、做学习笔记、沉淀团队文档都适用花十几分钟配置一次后面能省下大量改图时间。1. 先搞清楚Markdown 图片到底卡在哪一环1.1 一张图片在 Markdown 里的完整旅程很多人第一次遇到图片失效时第一反应是换博客平台结果换了一圈问题依旧。Markdown 里的图片语法是这个地址可以是一个本地相对路径也可以是一个完整网址。当你在本地用 Typora 写笔记时它默认会把截图保存到某个文件夹并在文档里填入./assets/xxx.png这样的相对路径。Typora 自己能解析是因为图片文件就在你电脑里一旦文档被复制到线上平台、在线文档或者同事的电脑这个相对路径对应的文件夹并不存在图片自然裂开。换句话说Markdown 图片失效的本质是引用关系被打破。要让图片在任何地方都能展示唯一可靠的思路是把图片放到一个所有终端都能访问的公共空间然后用一个绝对的网络地址去引用。这个公共空间就是图床。理解了这一点后续所有配置都围绕同一件事展开把本地文件移动到远端并拿回一个通用链接。1.2 本地管理和图床管理的本质区别本地管理图片你得到的是一个个.png、.jpg文件夹文件归自己掌控缺点是文档一挪窝就失效。图床管理图片你得到的是一个 URL文件不在手边但任何连接网络的设备都能打开。两者各有利弊关键看你要文档“能跑得远”还是“文件一定在自己手里”。维度本地文件夹图床Gitee分享便利性低必须带着文件夹一起传高复制 URL 即可成本零成本免费额度即可起步维护负担需要手动迁移、打包基本零维护稳定性硬盘损坏、误删即丢失依赖平台稳定性和使用规则适用场景永远只在本地看的私密笔记博客、文档、协作、公开分享如果你写的东西只在本地自己看本地路径完全没问题但只要存在任何一次跨设备、跨平台的分发需求图床就是绕不开的选择。很多人的误区是把“本地备份”和“图床”对立起来其实它们可以共存图床负责对外链接的稳定访问本地依旧保留原图作为备份这样两边的好处都拿到了。1.3 一套图床方案的完整工作链路动手之前先把链路理清。你在 Typora 里拖入一张截图Typora 并不会直接把图片变成链接它需要一个“搬运工”PicGo 就是做这件事的。PicGo 启动后会在本地开一个小服务Typora 把本地图片交给这个服务PicGo 再通过 Gitee 的开放接口把图片传到你预先建好的仓库拿到一个图片直链最后 Typora 自动把 Markdown 里的本地路径替换成这个网络链接。整个流程只有三步本地图片出现 - PicGo 上传到 Gitee 仓库 - Typora 拿到链接并写进文档。链路听起来很简单但每个环节都有一些容易踩坑的细节尤其是令牌权限、仓库可见性、分支名这些配置往往“一步错全盘错”。后面我会按搭建顺序逐个说明这也是我第一次配置时反复折腾后总结出的最稳妥路径。2. 工具选型为什么是 Typora PicGo Gitee 这一套2.1 Typora 把写作体验和图片处理一体化Markdown 编辑器有很多Typora 能被大量用户当作主力核心原因是“所见即所得”输入 Markdown 语法界面直接渲染成排版后的效果不需要同时开两个窗口。这听起来不算什么优势但对每天写字的人来说沉浸感差别很大。真正让 Typora 适合做图床集成的是它在偏好设置里提供了完整的图片上传配置。你可以把“插入图片时的默认动作”直接设为“上传图片”还可以选择一个图床客户端作为上传服务。这意味着你不需要每张图都手动操作只要把图拖进编辑器后续的一切都是自动的。对比之下很多编辑器要么需要自己写插件要么只能手动复制图片地址体验差距就在这里体现出来。2.2 PicGo 把“上传”变成一次看不见的操作PicGo 是一个开源图床客户端它的核心价值是把“上传图片”这个动作从打开网页、选择文件、点击上传、复制链接这四五步压缩成一次右键菜单或自动调用。PicGo 支持多种图床默认界面里内置了部分常见图床但 Gitee 并不在列表里需要安装社区插件 gitee-uploader 才能启用。安装完之后PicGo 左侧会出现“码云”相关入口。这个插件上传图片的原理是调用 Gitee 的“创建文件”接口每一次上传本质上都是往你的 Gitee 仓库提交一个新文件和你在网页上上传一个文件没有区别只是交给了 API 去做。明白了这个原理后面很多报错就能看懂——既然本质是提交文件到代码仓库那么仓库存在与否、分支存在与否、令牌有没有写权限都会直接影响成败。2.3 Gitee 做图床的甜与苦选择 Gitee最直接的动机是免费、国内环境下载速度快、注册门槛低。很多主流的对象存储服务需要实名、付费甚至要动态绑定云账号对只想好好写笔记的人来说太重了。Gitee 就是一个代码托管平台注册之后建仓库就能用图片上传走的是普通仓库接口成本几乎为零。但它毕竟不是专门做图床的有几个问题必须正视。第一仓库容量有限制图片是二进制文件一张截图几百 KB几万张下来很容易把仓库撑大平台对仓库体积过大会有提示。第二Gitee 仓库内容需要符合平台规则图片仓库如果被判定为纯图床用途存在被限制或要求删除的风险。第三外链的稳定性不如专业对象存储图片放在 Gitee 上哪天平台调整防盗链策略历史图片可能大面积受影响。基于这些原因我的建议是把它定位成“个人写作初期的免费图床”重要图片一定要在本地留备份别把唯一副本交给任何免费服务。2.4 其他图床方案的对比参考如果你已经在几个方案之间犹豫不妨快速对比一下。常见的免费图床方案还有 GitHub PicGo但国内环境访问速度波动较大国内云厂商的对象存储价格便宜稳定性最高但首次配置稍微复杂有些极简图床网站只支持手动上传无法和 Typora 联动不适合批量写作。Gitee 方案最大的优势是“国内访问快 API 开放 免费”最大的劣势是容量限制和规则不确定性。这套组合适合作写作者的入门方案等图片量真正上来后再考虑云存储也算一条平滑的升级路径。3. 从零搭建Gitee 仓库、私人令牌、PicGo 联动3.1 建仓库前先想清楚的 4 个设置第一步是去 Gitee 新建仓库。仓库名称可以按照个人习惯来比如markdown-images、picgo-bed只要能看懂用途就行。建仓库时有几个选项如果不注意后面会踩坑。仓库必须选择开源。这是很多人最容易忽略的一点。PicGo 上传图片后Markdown 里引用的是链接如果你的仓库是私有的访问链接需要登录和权限别人打开你的文章依然是裂图。如果你确实有一些图片不想公开就不应该放图床别试图用私有仓库来兼顾私密那样做图床就失去了意义。初始化设置建议勾选“使用 Readme 文件初始化仓库”。如果建一个完全空白的仓库仓库就没有默认分支PicGo 调用接口时找不到可在哪个分支提交文件容易报分支不存在。先初始化出一个 README等于给仓库确定了一个默认分支PicGo 里填的分支名才能对应上。顺便在初始化完成后去仓库页面确认一下默认分支到底是master还是main不同时期创建的仓库可能不同记下这个分支名后面要用。最后是仓库描述随便填一个可见用途说明就好。Gitee 对仓库的“项目描述”可能会有校验尤其当仓库是图床用途时描述越明确越不容易被误判。3.2 私人令牌最容易忽视的一环Gitee 不像某些平台允许直接用账号密码做 API 鉴权它要求使用私人令牌也就是 Personal Access Token。这是整个配置里最需要留意的部分。生成位置在 Gitee 网页端进入个人设置 - 安全设置 - 私人令牌点击生成新令牌。生成时会让填写令牌描述比如typora-picgo方便日后认出来。关键是权限范围的选择我测试下来至少要勾选与 projects 相关的读写权限。Gitee 的权限界面偶尔会更新如果你不确定就优先把“projects”相关的读、写权限都勾上不要只勾只读否则上传会被拒。令牌生成后页面只会完整显示一次关闭页面就再也看不到了。我第一回没当回事复制完顺手关掉后来换电脑要重新填只能重新生成一个再配一遍。正确的做法是生成后立刻存到密码管理器里或先在本地记录一份再操作。令牌相当于你账号在某些接口操作下的密码千万别把它直接提交到公开仓库泄露了就去令牌列表里删除重建不要抱着侥幸心理继续用。3.3 PicGo 安装 gitee-uploader 插件与参数逐项填写下载安装 PicGo 客户端后第一次打开先别急着配任何参数去“插件设置”页面搜索gitee-uploader找到后安装。安装完成后左侧栏会多出“码云”或类似命名的一栏点进去才是真正的配置界面。填参数时最核心的是这几项。repo必须填用户名/仓库名这种完整格式比如你 Gitee 用户名是zhangsan仓库名是markdown-images就填zhangsan/markdown-images。注意不是只填仓库名很多人第一次在这里报错。branch填仓库默认分支名就是刚才让你记下来的那个是master就填master是main就填main。token填入刚才保存的私人令牌建议直接粘贴并检查有没有多余空格。path项表示图片上传到仓库后的目录前缀我习惯填img/这样所有图片都收在仓库的 img 目录下仓库本身不会乱。customPath是动态子目录默认可以留空也可以按需配置年/月日之类。customURL一般留空让插件自己拼接 Gitee raw 链接。保存后先去 PicGo 主界面拖入一张测试图片选择码云上传。如果返回了一个 URL说明 Gitee 端的配置已经通了可以进入下一步。3.4 上传成功后才算真正的第一步有的朋友填完参数不测试就直接去 Typora 里配置结果上传失败一下子分不清是 PicGo 的问题还是 Typora 的问题。所以务必在 PicGo 单独跑通一次测试。测试图片选一张小图就行如果上传成功去 Gitee 仓库的img目录下能看到这个文件同时 PicGo 日志窗口会显示上传成功和返回的 URL 链接。这一步能确认的仓库地址没问题、分支没问题、令牌权限没问题、插件配置没写错。排除这些变量之后再去配 Typora万一后面出问题排查范围就缩小很多。这也是我调试这类工具链的习惯逐层验证不要搭好一整条链路再去猜 bug。4. Typora 对接 PicGo配置完成后全程无感4.1 图片偏好设置里的关键选项打开 Typora 的偏好设置找到“图像”分类。这里有三个关键设置插入图片时的默认动作、上传服务提供商、PicGo 可执行文件路径。“插入图片时”这一项要选择“上传图片”。注意这个选项的意思是你每拖入一张图片Typora 会直接走上传流程如果你还希望本地保留原图可以在文件层面自己留一份不影响 Typora 的上传行为。上传服务选择PicGo(app)然后在下面指定 PicGo 的安装路径。Windows 上一般是安装目录里的PicGo.exemacOS 上需要找到.app包路径命令行工具则要定位到picgo可执行文件。如果路径没填对Typora 会提示找不到应用这时先去文件管理器里确认你的 PicGo 到底装在哪里。还有个容易被忽略的点Typora 通过本地接口调用 PicGo 时PicGo 必须已经在后台运行。很多人的习惯是写完文档顺手退出 PicGo之后再写新文档上传图片就会失败因为 Typora 调用不到那个本地服务。建议把 PicGo 设置为开机自启让它一直驻留在系统托盘里写作时就不用再想这件事。4.2 第一次验证“粘贴即上传”配置完成后新建一个测试文档拖入一张图片。正常情况下图片会从本地路径自动变成一个完整的网络链接。判断它是否真的成功不要只看 Typora 界面里图片是否还显示因为 Typora 有本地缓存就算链接是坏的它也可能显示给你看。更可靠的验证方式是去 Gitee 仓库刷新页面看img目录下是否出现这个新图片文件或者直接打开 PicGo 的上传日志日志里会显示上传结果和返回的 URL。如果拖入图片后 Typora 里还是本地相对路径多半是“插入图片时”没有设为“上传图片”或者没勾选下方对现有图片应用该规则。如果有旧文章里已经插入了大量本地图片可以后续统一处理但对于新建文档务必保证默认行为就是上传。4.3 图片链接格式与常见误解上传成功后Typora 里生成的链接长这样这里的关键是raw字段它表示返回的是原始文件内容而不是仓库的文件页面。很多人误把仓库的文件网页地址当成图片链接那种地址打开是网页不是图片放进 Markdown 后也无法被正常渲染。你只需要记住图片链接的路径里一定要包含raw这是 Gitee 图床能用的前提。另外图片文件名最好不要带中文。虽然 Gitee 的 raw 链接在某些情况下能处理中文但不少平台在解析中文 URL 时会出问题还有可能被转成百分号编码导致某些 Markdown 渲染器无法识别。PicGo 上传时如果有开启时间戳重命名等功能文件名会自动变成数字串这是最省事的做法如果你习惯自己截图后手动命名尽量用英文字母和数字。4.4 剪贴板链接还有一个附加用途Typora 集成只是图床的一个出口PicGo 本身也是一个独立的上传工具。比如你在写汇报、做幻灯片时需要把某张图快速放到一个在线文档里可以不用打开网页直接在 PicGo 拖入图片它会把 Markdown 格式的链接自动复制到剪贴板你粘贴到哪里都能用。在 PicGo 设置里可以把默认链接格式改为 Markdown、URL 或 HTML按使用场景取舍。这一点往往被教程忽略但对日常办公来说非常实用。我经常在微信对话、在线表单里需要临时贴图打开 PicGo 拖图进去然后粘贴链接整个流程不超过五秒比打开图床网页慢慢传要快得多。5. 常见问题排查看这里我踩过的坑都在这些5.1 上传失败时先看日志不要反复重试PicGo 的“上传日志”标签页绝不是摆设。凡是上传失败日志里都会给出具体错误码或错误信息排查的第一步必须是这里。很多人失败后选择反复重新上传结果只在日志里刷出一排同样的错误纯属浪费时间。正确的姿势是把日志里的错误信息复制下来对照错误码去定位。例如日志提示401基本可以确定是令牌问题。要么是令牌内容被复制多了一个空格或多个字符要么是令牌权限没有勾选写权限。建议回到令牌列表重新生成一个新的粘贴时注意不要带换行符。如果提示403通常也是令牌权限不足重点检查 projects 相关权限中的写入权限。如果是422这类参数类错误问题大概率出在仓库分支或者路径上。打开仓库页面确认默认分支究竟是master还是main再对照 PicGo 里填的内容一个字都不能差。仓库如果是空的而且没有初始化 README同样可能出现分支不存在的报错先去仓库里提交一个 README 文件让分支存在然后再试。5.2 图片裂开不一定是上传失败有时日志显示上传成功Typora 里也有网络链接但文章发布到某个平台后图片还是裂的。此时要区分两种情况。第一种是链接本身有问题例如不是raw链接第二种是目标平台主动屏蔽了外部图片很多博客平台、公众号编辑器都有防盗链机制不加载来自外部域名的图片。如果是第二种这是 Gitee 免费图床的天然局限靠配置解决不了。常见的对策有三个换一个允许外链的平台发布用支持图片转存功能的写作工具或者干脆把图床升级为带独立域名访问的对象存储。免费方案能解决的问题有边界图片量上来之后该花的成本还是得花。5.3 Gitee 仓库体积和平台限制的应对思路Gitee 仓库有容量限制图片文件又属于比较快速的体积增长类型。用过一段时间后你会发现仓库体积涨得比想象中快因为每一张截图少说几十 KB多则几 MB。这也意味着不能把 Gitee 当永久仓库来用得有点规划。我常用的做法是“图片瘦身”截图工具保存的 PNG 文件很大上传前用压缩工具转成 JPEG 或 WebP画质损失不大体积能减少一半以上。另一个办法是按时间段整理仓库比如每年建一个图床仓库避免一个仓库无限膨胀。更重要的是原图一定要在本地或网盘里留一份图床里存的只是对外分发的那份副本。5.4 换了电脑配置怎么快速恢复图床配置说多不多但重新填起来也麻烦尤其是 Gitee 仓库名、分支、令牌这些细节时间一长很容易记混。PicGo 的配置其实都保存在本地数据文件里我习惯在配置稳定后直接把整个 PicGo 数据文件备份一份到网盘。换电脑时装上同样的 PicGo 版本再用备份文件覆盖回去所有图床配置一次恢复不需要重新走一遍全套填参数流程。如果你不打算备份配置文件那至少要把令牌存到密码管理器里仓库名和分支名记到笔记里。不要临时去翻网页更不要在聊天记录里找令牌那样既低效也安全风险很高。5.5 杂项问题速查表现象可能原因处理建议Typora 提示无法连接 PicGoPicGo 未运行或路径填错启动 PicGo确认后台托盘图标存在上传后链接打开是网页不是图片缺少raw检查链接格式改为 raw 直链图片在博客后台不显示目标平台外链屏蔽换平台或换图床上传速度很慢图片太大或网络波动先压缩图片再重试仓库里图片目录很乱未设置 path在 PicGo 插件里统一设置img/路径删除图片后发现链接依然能访问缓存或已提交记录无需处理旧的 raw 引用可能保留5.6 一个心理预期层面的提醒每次有人让我推荐图床方案我都会先说一句免费方案要做好“随时可能失效”的心理准备。Gitee 不是专门做图床的平台它随时可能调整规则仓库也可能因为触发限制被要求整改。图床可以免费你的重要图片不能没有退路。所以从第一天起就应该把图床当成“分发加速层”而不是“唯一边界”。原图备份的习惯远比图床本身重要。我用这套方案写了很长一段时间从本地笔记到线上博客再到跨设备协作图片再也没有成为阻碍。最深的体会是好的工具链不是让你多做什么而是让你少操心。Typora、PicGo、Gitee 这三者单独拿出来都很简单组合在一起才真正解决了 Markdown 写作者的痛点。配置过程中你会遇到一两次报错照着日志排查基本十分钟内都能解决。最后再分享一个小习惯每次给图片仓库瘦身后我都会顺手在仓库首页写一条更新说明记录这次清理压缩了哪些内容、迁移了多少图片。等仓库体积再次接近限制时回看记录就能快速定位到可迁移的文件不用翻着文件列表懵圈。这套流程跑顺之后你会觉得当初那十几分钟配置时间花得相当值。