很多写 Markdown 的朋友最开始都会把图片存在本地文件夹里。本地存图写文档那会儿确实省心但一旦换了电脑、想把文章发到博客或者给同事看问题就出来了图片全挂到处都是裂图图标。我那时候最开始用线上图片服务快是真快可免费额度说没就没后来的收费方案对个人玩家不太划算。后来折腾出一套不用花一分钱、又能长期稳定的方案就是用 Typora 配 PicGo 再挂到 Gitee 上也就是常说的码云图床。这套方案跑了一阵子整理一篇完整的配置记录出来顺便把踩过的坑也一并写清楚。1. 图床方案选型与整体链路拆解先聊聊为什么要用图床以及为什么最后定下来是 Typora 加 PicGo 加 Gitee 这么一套组合。Markdown 文件本质是纯文本图片没法像富文本那样“嵌”进文档里。Markdown 里写一张图片引用的其实是一个 URL 地址。你用本地相对路径比如这个路径只在你自己的电脑上有效。发到网上别人电脑上根本没有img/photo.png这个文件自然就显示不出来。图床要做的事情就是把图片文件放到一个互联网上能直接访问的位置生成一个公网 URL让谁都能通过这个链接看到图片。市面上图床方案大致分三类。第一类是直接用平台自带的图片上传功能比如在博客后台粘贴图片。这种方案很简单图片自动传到平台服务器上但缺点也很明显图片和平台绑定。你在这家平台发的文章如果某天想搬到自己的博客或者另一个平台图片没法跟着走全还留在原平台。等于文字搬走了图全留在那儿了文章还是残缺的。第二类是找专门的图床服务商。这类服务大多打着“免费图床”的旗号用起来也确实方便注册完往上一传就有链接。但我个人不建议把重要图片存这类服务上免费图床的稳定性往往没有保障图片链接可能过几个月就失效了。你前期写得越多后面图片清零的风险就越大这种方案适合发临时图片不适合做正经的内容沉淀。第三类就是自建图床也就是基于对象存储或者代码托管平台来做。对象存储如各大云的 OSS 服务稳定性和速度都很好但要实名认证、开通服务、看计费规则对只是想写写文档的人来说门槛偏高。代码托管平台的好处是你本来就在上面放代码顺手开个仓库存图片基本零学习成本也不涉及开通什么额外服务。Gitee 在这类平台里有个天然优势国内的访问速度快。写笔记的图基本都是国内访问场景图片放在国内平台加载速度会比放在国外服务器上明显快一截。而且 Gitee 个人仓库不限数量存图片完全够用。我之前也试过其他代码托管平台要么访问速度不理想要么免费版有心跳限制用来当图床总有点别扭。Gitee 没有这些限制所以最后定下来用它。这套链路跑起来的流程是这样的你在 Typora 里写文章插入一张图片Typora 把图片交给 PicGoPicGo 负责把图片上传到 Gitee 的仓库里上传成功后返回图片的直链地址Typora 拿到这个地址自动贴到 Markdown 里。整个过程不需要你手动去复制图片、打开网页、上传再复制链接回来。从你粘贴图片到文档里显示出来中间几秒钟就完成了完全是流水线式的体验。整个方案用到的工具有三个分工也明确。Typora 是写作前端负责捕获你粘贴的图片并调用外部程序PicGo 是中间桥梁承担了接收图片、上传图片、返回链接的角色Gitee 是最后的存储位置图片最终以文件形式躺在仓库里通过 Gitee 的链接供公网访问。2. 准备工作搭建 Gitee 图床仓库并获取访问令牌整个链路里Gitee 这端需要准备两样东西一个存图片的仓库一串访问令牌Token。仓库用来装图片令牌是 PicGo 上传图片时用来验证身份的凭证。2.1 创建图片仓库命名、开源与初始化选择在 Gitee 上新建仓库时有几个配置项需要认真对待。仓库名称建议用纯英文加连字符比如my-image-hosting或pic-bed。这是因为图片 URL 最终会包含仓库名中文仓库名在拼接 URL 时可能被转义成一堆百分号编码不仅难看个别场景下还可能造成兼容问题。用英文名就完全没这些烦心事。仓库是否公开取决于你对图片传播范围的要求。私有仓库也能作为图床用但有一个前提条件必须配合 Token 认证。在 Gitee 上私有仓库的文件链接不发 Token 给外部访问者时是无法直接预览的但你只要在访问图片的 URL 里带上 Token 参数链接依然可以被浏览器加载。问题是这样的链接会赤裸裸地暴露你的令牌一旦链接被别人拿到你的仓库也就等于被看到了。除非你的图片真的极度私密我建议直接建公开仓库图片本身就希望被访问公开了反而省事。初始化仓库那一栏还有一个选项叫“使用 Readme 文件初始化这个仓库”。建议勾上它。这个选项会自动帮你生成master分支并完成初始提交。不勾选的话仓库是空的PicGo 上传时可能要处理分支不存在、仓库为空等边界情况配置起来更麻烦。勾选后仓库自带主分支结构后面配置 PicGo 时直接用主分支的名字即可省去不少弯路。仓库建好后进入仓库首页记得看一眼地址栏。完整的仓库地址一般长这样https://gitee.com/你的用户名/你的仓库名。后面配置 PicGo 时仓库信息里的owner填用户名repo填仓库名这两个值不要填反。2.2 申请私有令牌权限设置与安全须知Gitee 的 Token 机制用来替代账号密码完成第三方程序的授权。这个令牌在 Gitee 上叫做“私人令牌”生成入口在个人设置里面点头像进入个人主页找到“设置”一栏然后进入“私人令牌”页面点击“生成新令牌”。生成令牌时有一份权限列表需要勾选。PicGo 需要读取仓库信息、上传文件到仓库的能力所以基本只要把projects相关的权限勾上就行。我当时勾选的是projects下的所有权限实测下来上传图片完全够用。不建议图省事把所有权限全勾了令牌权限越大泄露后的风险也越高。够用就好这是最基础的安全常识。提交生成请求后页面会展示一串新令牌。这串令牌只会出现这一次刷新页面后就再也看不到了务必当场复制保存。如果忘了复制只能重新生成一个新令牌。令牌本身是字母数字组成的字符串通常会以开头几个字母标识可以把它想象成你仓库的一把备用钥匙谁拿到它谁就能往你仓库里传文件。安全上还要提一句这个令牌建议放在自己的密码管理器或者私人笔记里不要提交到代码仓库不要写在配置文件里上传到 GitHub、Gitee 这类公开地方。如果发现令牌可能泄露了最快的处置方式就是去令牌管理页面删掉它、重新生成一个新令牌再更新 PicGo 里的配置。2.3 版本选择提示软件版本与仓库结构的配合仓库建好了令牌拿到了这端的准备工作就结束了。有一点提醒一下Gitee 的仓库分支名新仓库默认是master。PicGo 配置里填的branch字段要和仓库的实际分支名完全对应否则上传时会报“分支不存在”之类的错误。很多人在这一步卡住其实不是配置写错了而是仓库分支名和配置里的分支名对不上。比如仓库实际分支是master配置文件里填了main那上传必然失败。开工前先在仓库页面确认好分支名再填到配置里可以少走不少弯路。3. PicGo 安装与 Gitee 图床插件配置PicGo 是这条链路里承上启下的角色。先安装 PicGo 客户端再装 Gitee 插件然后把仓库信息和令牌填进去上传通道就算通了。3.1 PicGo 客户端安装与界面速览PicGo 是开源的图片上传工具提供了 Windows、macOS 等桌面版本。去它的官方网站或者项目发布页下载对应系统的安装包安装过程没有特殊操作一路默认即可。装好后打开的界面很简洁主要是左侧几个功能栏目“上传区”默认页、“图床设置”、“相册”等。“图床设置”里列出了 PicGo 内置支持的各种图床比如腾讯云、阿里云、七牛云等往下拉还能看到一个“插件设置”入口Gitee 图床就是通过插件方式接入的。PicGo 刚装好时默认是空的直接去“图床设置”里找 Gitee 是找不到的因为 Gitee 的插件是社区贡献的、默认不在内置列表里。需要先到“插件设置”页面搜索并安装 Gitee 插件安装完成后才在“图床设置”里看到 Gitee 的配置入口。这一步很多人漏了以为默认就有愣是找不到 Gitee 选项。安装插件时有一个值得注意的细节PicGo 的插件本质上依赖 Node.js 环境如果电脑上没装 Node.js插件安装可能失败。遇到安装报错先去装一个 Node.js LTS 版本再回来安装插件。这个坑我踩过当时插件一直装不上看了日志才发现是缺 Node.js 环境。3.2 Gitee 图床插件配置项逐项拆解装好插件后进入图床设置里的 Gitee 配置页。界面会列出几个待填的字段每个字段的含义和填法都不一样。repo字段填的是仓库地址的完整路径但不需要带https://gitee.com/的前缀格式是“用户名/仓库名”。比如你的用户名是samzhang仓库名是my-image-hosting这里就填samzhang/my-image-hosting。严格按这个格式来不要多加空格不要多写斜杠。branch字段填仓库的主分支名新仓库一般是master。这里填错了会直接导致上传失败前面已经提过了再提醒一遍。token字段填入前面生成的私人令牌。粘贴时注意不要把前后的空格带进去有些系统复制时会在末尾多带一个换行符肉眼看不见但程序读到了。path字段是图片存储的目录路径。比如填img/图片就会传到仓库下的img目录里不填就默认传到仓库根目录。个人建议设置一个独立的目录比如img/或者images/将来仓库里除了图片还有其他文件时分类清晰也方便管理。customUrl字段比较关键决定最终生成的图片链接长什么样。这里如果不填PicGo 默认生成的链接是https://gitee.com/用户名/仓库名/raw/分支名/图片路径这种格式直接能访问实测没问题。如果你有自定义域名可以在这一栏填写自定义域名前缀PicGo 会用自定义域名/图片路径的形式生成链接。defaultUrl字段是默认的前缀模板一般保持默认https://gitee.com不动除非你知道自己在做什么才去修改。配置完成后务必点击图床设置里的“设为默认图床”按钮。这一步的作用是让 PicGo 之后的图片都走 Gitee 这个通道。如果不点PicGo 可能还在用其他图床配置或者什么都不用图片上传就会失败或走错地方。3.3 上传验证与第一张图配置填好后直接到 PicGo 的“上传区”拖一张图片进去看它能不能成功上传并返回链接。这一步先验证 PicGo 本身工作是否正常后面再接入 Typora 时出问题了才知道问题出在哪一环。上传成功的话“相册”区域会显示刚上传的图片旁边的链接区出现图片地址。可以把这个链接复制到浏览器里打开能正常显示图片说明 PicGo 到 Gitee 这一段的链路已经打通了。如果上传失败PicGo 界面会给出错误信息。最常见的是 TOKEN 错误或仓库权限不足常见的就是 TOKEN 复制错了、权限没勾全或者仓库地址填错了。照着 2.2 节的步骤重新确认一遍基本能解决。4. Typora 偏好设置将图片上传无缝接入写作文档流程PicGo 这端通了接下来就是把 Typora 接进链路里。Typora 是一款 Markdown 编辑器内置了“图片插入”和“外部程序调用”能力这正好是接入 PicGo 的接口。4.1 打开图片偏好设置在 Typora 菜单栏找到“文件”下拉菜单里选“偏好设置”然后切到“图像”这个标签页。这里集中了 Typora 与图片相关的行为配置。“插入图片时”这一项决定 Typora 对粘贴或拖入图片采取什么动作。默认行为一般是复制图片到当前文档的相对路径目录里。我们这里要改成“上传图片”让 Typora 直接把图片交给外部工具处理而不是先存本地。“上传图片服务”或叫“上传服务”选择“自定义命令”或“PicGo(app)”。Typora 的版本不同选项名称会有些差异。旧一点的版本有独立的“PicGo(app)”选项直接用即可新版本一般归到“自定义命令”里在命令框里填 PicGo 的可执行文件路径。关于 PicGo 的可执行文件路径Windows 上默认装在C:\Users\你的用户名\AppData\Local\Programs\PicGo\PicGo.exe这样的路径下。macOS 上通常是/Applications/PicGo.app/Contents/MacOS/PicGo。填好路径后Typora 调用这个程序进行图片上传。如果路径填错了或者程序名对不上Typora 会提示“上传失败”或“图片上传工具调用失败”。4.2 配置验证与 Ollama 场景补丁配置好后点“验证图片上传选项”按钮。Typora 会拿一张测试图片走一遍完整的链路调用 PicGo上传到 Gitee返回链接。验证成功的标志是弹窗提示上传成功并显示图片链接验证失败则会有具体的错误提示。测试通过后在 Typora 里写文章时插入图片的方式就是平常的粘贴。Typora 会自动把图片上传到图床并在文档里插入返回的 URL。你“看不到”上传过程因为它是后台完成的只有右下角或状态栏会有短暂的上传提示。这种全程无感的状态写作节奏完全不受影响。我个人在建图床之前笔记里大量图片都是本地相对路径。接好图床后一方面新插入的图都是在线链接另一方面我还做了一个整体体检把以前的笔记批量处理了一下把图片文件统一上传到图床把文档里的本地路径替换成在线 URL。虽然这个过程有点繁琐但一次性处理后笔记就变成真正的“纯文本搬家自由”了。有人问旧笔记里的图片怎么办可以用一个思路把旧笔记和图片目录关系梳理清楚然后写脚本或手动把图片传到图床再批量替换 Markdown 里的图片引用。这个比较适合一次性整理整理完之后笔记就完全脱离本地图片依赖了。4.3 优化图片存储路径前面提到 PicGo 的path字段建议设成img/那样所有图片都会传到仓库的img/目录里。这种单目录方案简单直观不过如果你图片量特别大可以考虑用年月维度分目录比如img/2025/01/这样仓库按时间归档后续找图会更清晰。需要注意的是Typora 调用 PicGo 时PicGo 拿到的文件名是 Typora 传过去的。如果 Typora 里的图片本来是“Pasted image 20250101120000.png”这种带空格的文件名PicGo 生成的链接里文件名也带着空格。虽然 Markdown 语法对带空格链接的支持度还行但空格还是可能造成一些解析不友好的情况。有一个小技巧在 Typora 偏好设置里可以配置图片重命名规则开启重命名后粘进来的截图会自动变成无空格的命名上传后链接里就不会出现空格了。5. 常见问题排查与操作经验实录这套链路跑下来碰到问题最多的环节集中在Token 配置、分支名不匹配、Typora 调用 PicGo 失败、上传成功但不显示这几个方向。整理成一个速查表放这里遇到问题可以直接对着查。故障现象可能原因处理动作PicGo 上传报 401Token 复制错误或权限不足重新生成 Token确认 projects 权限已勾选重新填配置PicGo 上传报仓库不存在repo 字段格式不对确认填的是“用户名/仓库名”并且仓库真实存在PicGo 上传报分支不存在branch 与仓库实际分支名不一致到仓库页面查看分支名把main改成master或反之上传成功但链接打不开customUrl / 分支名拼错浏览器里打开链接看 404 还是权限问题注意分支名大小写严格区分Typora 无法调用 PicGo可执行文件路径错误 / Node 环境缺失检查 PicGo 安装路径是否正确确认系统里 Node 环境存在上传图片后 URL 里有中文文件名含中文开启 Typora 图片重命名或在上传前自行改名私有仓库图片无法预览仓库私有未带 Token换公开仓库私有仓库不想公开就接受带 Token 的 URL 风险其中上传成功但浏览器打不开图片这一条我见过很多次。根本原因大多是customUrl配得不严谨或者branch分支名大小写写错了。Gitee 的 URL 对大小写敏感Master和master是两个不同的路径。打开 Gitee 仓库页面把地址栏里的分支名原样复制到配置里能避免不少这种问题。Typora 调用 PicGo 失败的另一个冷门原因是防火墙拦截。Windows 系统的防火墙有时会拦截 PicGo 的网络访问明面上 Typora 显示上传失败实际是 PicGo 根本没把图片发出去。遇到这种情况把 PicGo 加入防火墙的白名单或者临时关掉防火墙试一次就知道是不是这个原因了。换电脑时格外的注意事项PicGo 的配置和令牌都保存在本机换电脑后需要重新装一遍 PicGo、配上 TokenTypora 也得重新指一次命令路径。不是说你 Gitee 仓库建好了就万事大吉三方工具的配置都要重新来一遍。不过好在按前面的步骤操作十分钟不到就能完成一套配置。另外要说的一个体会是不要把主仓库当图床。图床图片是高频更新、大量文件堆积的仓库它和你的代码仓库混在一起会让仓库体积越来越大拉取代码时也会变慢。我现在是单独建了一个图床仓库让它专门接收图片代码仓库保持干净。这个习惯坚持下来后不管图床仓库怎么折腾都不影响代码工作心理负担也小很多。6. 从本地图片到在线图床的迁移经验如果你的笔记体系里已经积累了相当数量的本地图片直接把图片转到图床并替换引用是一次性整理的好机会。整理的做法不复杂但涉及大量文件的场景里有一些细节值得提前想清楚。先梳理图片分布。旧笔记的图片路径一般有两类一类是相对于 Markdown 文档的相对路径比如./images/xxx.png另一类是项目的固定静态资源目录比如docs/images/xxx.png。前者需要逐个文档处理后者可以把整个目录打包传到仓库里再根据目录结构生成链接最后批量替换 Markdown 文件中的引用。上传大目录时PicGo 支持批量拖拽也可以把整目录先打包传到仓库这个方案对一次处理几百张图片更快。上传完成后整理出一张“原文件名 - 新链接”的对照表然后写一个简单的查找替换脚本把 Markdown 里所有旧路径替换成新链接。替换后务必抽查验证。Markdown 渲染器对图片 URL 的处理宽容度不高个别链接末尾多一个空格、少一个斜杠都会导致整张图出不来。建议用脚本统一检查所有 Markdown 文件匹配 Markdown 图片语法逐个请求链接看返回状态码是不是 200。这一步能把遗漏的坏链全部找出来一步到位。7. 写在最后的操作心得这套 Typora PicGo Gitee 的方案我已经用了相当长一段时间期间只有一次 Gitee 仓库临时故障导致图片短暂无法访问整体稳定性还是对得起它的免费属性的。作为个人笔记、技术文档、博客配图的图床方案它完全够用。唯一要留意的还是那句话别把令牌放到公开地方别把私密图片传到公开仓库。这套系统适合的是技术文章配图、学习笔记插图、生活记录照片这一类的常规内容需要真正私密管理的文件本来就该走本地加密或其他私有存储方案而不是往任何图床里塞。整个过程配置下来真正的成本主要在那一次性的十来分钟设置。以后每次写文章、记笔记插入图片就像粘贴图片一样轻松图片自动上传、链接自动生成Markdown 文档随时可以搬走、发布、分享再也不会出现换个地方看文章全是裂图的尴尬事。如果说有什么建议给刚开始用 Typora 的朋友我想说图床这步不要拖写笔记从第一天就用在线图床省下的都是后面对着一堆失效链接叹气的时间。