前两天想给一篇技术笔记配图截图之后顺手按下快捷键PicGo弹了个通知说上传成功。我心想还挺顺结果往文章里粘贴链接的时候才发现图片根本打不开。回头看了一眼日志里面躺着一行红字上传失败:网络请求错误 (async upload fail error: 系统错误)。这个报错我太熟了。玩博客、写文档、搭个人站的人只要用的是PicGo GitHub 图床这套组合几乎都撞过类似的墙。明明配置填了好几遍Token也复制了仓库名也对得上可图片就是传不上去。这篇文章不打算讲什么高深原理就是把“PicGo上传图片到Github仓库上传失败”这个场景彻底拆开从上传链路、配置项、网络环境、Token权限、分支名、文件大小这些最容易被忽略的环节一步一步带你排查到底。无论你是刚配好图床的新手还是已经踩过几次坑的老手照着这篇文章走一遍基本能找到问题根源。1. 先看懂PicGoGitHub图床的上传链路很多人一看到“网络请求错误”就把锅甩给PicGo觉得是软件坏了。其实不是。PicGo本身只是一个客户端真正干活的是GitHub的API。想排查问题得先搞清楚一条图片从剪贴板到仓库到底经过了哪些环节。1.1 一次上传背后到底发生了什么PicGo上传图片到GitHub本质上就三步你把截图复制到剪贴板PicGo读取剪贴板里的图片数据。PicGo把图片二进制内容转成Base64然后调用GitHub的contentsAPI向https://api.github.com/repos/{用户名}/{仓库名}/contents/{路径}发送一个PUT请求。GitHub API收到请求校验Token权限把图片文件写入对应仓库分支然后返回一个包含文件信息的JSON响应。PicGo拿到响应之后组合出图片的访问链接例如https://raw.githubusercontent.com/{用户名}/{仓库名}/{分支}/{路径}再复制到你的剪贴板里。所以如果链路中任何一环出了问题你看到的报错内容会完全不一样。比如Token带错返回的是401认证失败仓库名填错返回404文件同名冲突返回422网络出问题则可能直接是“网络请求错误”。理解了这条链路排查就不会像无头苍蝇一样乱试。1.2 失败消息怎么归类观察实际遇到的报错大致可以分成三类配置类错误仓库名写错、分支名写错、Token缺失或权限不足。这类报错通常来自GitHub的明确响应比如Authentication failed、404 Not Found、422等。网络类错误请求没到达GitHub或者响应没回来。常见的就是“网络请求错误”“系统错误”“timeout”也有不少情况是DNS解析失败、防火墙拦截、系统时间不准确导致的SSL握手失败。资源类错误文件名冲突、文件太大超过GitHub限制、仓库容量超限、API限流。这类错误往往在配置完全正确的状态下出现非常容易被忽略。我个人习惯是先判断报错字符串属于哪一类再决定从哪个方向查。否则一上来就删Token重新生成折腾半天发现白忙一场。2. 配置核查多数失败都栽在不起眼的地方很多“上传失败”其实不是网络问题而是配置项里藏着雷。下面这几个配置点是我见过最高频的“翻车现场”。2.1 Token的权限与有效期GitHub Token是访问仓库的钥匙也是最容易出错的地方。如果你用的是Classic Token生成时一定要勾选repo权限这是个合集权限包含仓库内容的读写。只勾了read:user或者干脆没勾权限PicGo上传时就会收到403或者401。如果你用的是Fine-grained Token就要更小心。这类Token默认没有仓库权限需要在Repository access里选择All repositories或者Only select repositories然后在Permissions里把Contents设为Read and write。很多人生成的时候随手选了只读结果上传必定失败。另外Token的过期时间也是个隐形坑。GitHub现在生成的Token默认会设置有效期常见的是7天、30天、90天。过期之后PicGo不会给你任何“Token过期”的明确提示只会表现为上传失败日志里写着认证错误或者网络错误。如果你已经很久没有重新生成过Token那大概率是它悄悄失效了。2.2 仓库名和分支名格式PicGo设置里的“仓库名”并不是随便填个名字就行格式必须是用户名/仓库名。比如你的GitHub用户名是zhangsan仓库是blog-images那就填zhangsan/blog-images少一个部分或者多一个空格都会触发404。分支名更是个大坑。早些年GitHub默认分支是master而现在新建的仓库默认是main。如果你在PicGo里填的分支名和仓库实际默认分支不一致请求就会落到一个不存在的分支上结果当然还是404。检查方法很简单打开仓库页面看左上角的分支下拉框默认显示的是什么PicGo里就填什么。提示分支名不要凭记忆填一定要去仓库页面确认。很多老仓库从master改成main之后图床配置里的分支名还停留在过去。2.3 存储路径与自定义域名“存储路径”指的是图片在仓库里的目录前缀比如填img/图片就会传到仓库的img目录下。这个字段可填可不填但如果你填了要留意路径末尾是否带斜杠以及拼写是否正确。目录不存在时GitHub API会自动创建所以路径本身不会导致失败但会影响最终图片链接的拼接。“自定义域名”这个字段大部分人填的是https://raw.githubusercontent.com然后加上用户名、仓库、分支、路径拼接出最终访问链接。如果你填错了域名格式比如漏了https://或者路径结构配错了就会出现一个很迷惑的情况上传日志显示成功但复制出来的链接在浏览器里打不开。这种“假成功”比明确报错更难排查。所以我建议配置完图床后先不要急着写文章先手动上传一张测试图复制链接放浏览器里打开看看。如果链接能直接看到图片说明整套链路是通的。3. 一步一步排查网络与认证问题如果配置项检查下来都没问题那就要开始动手做联调了。这里分享一套我用过很多次的排查流程每一步都能帮你缩小问题范围。3.1 先用命令行独立验证连通性排除PicGo自身因素的影响先确认你的电脑能不能正常访问GitHub相关服务。打开终端执行下面这条命令curl -I https://api.github.com如果返回了HTTP/2 200说明本机到GitHub API这一段的网络是通的。再试一下raw文件服务的连通性curl -I https://raw.githubusercontent.com如果你连这两条命令都不通或者一直卡住没有响应说明问题出在本地网络环境上而不是PicGo配置的问题。这时候先恢复本地网络环境再回头测试PicGo。3.2 验证Token是否真的有权限网络通的情况下下一步就是验证Token本身。GitHub提供了一个接口可以查看当前Token的用户信息curl -H Authorization: token 你的Token https://api.github.com/user如果返回了JSON里面有login: 你的用户名说明Token本身是有效的。如果返回401说明Token已失效或格式有问题。这还没完Token有权限不代表对目标仓库有权限。继续执行下面这条命令确认Token能写入目标仓库curl -X PUT \ -H Authorization: token 你的Token \ -H Content-Type: application/json \ -d {message:test,content:dGVzdA} \ https://api.github.com/repos/你的用户名/你的仓库名/contents/test.txt这条命令会在仓库根目录创建一个内容为test的文本文件。如果返回201和文件信息说明Token对该仓库的写权限没问题问题基本可以锁定在PicGo配置上。如果返回403或者404那你得回去检查Token权限或仓库名。注意执行完这条命令后记得去仓库里把测试文件删掉或者不要在意这个遗留文件。如果介意就跳过这一步直接在PicGo里测试上传更快。3.3 查看PicGo日志和测试上传PicGo自带日志系统。进入设置把日志级别调整为error重新触发一次上传然后去日志目录翻最新记录。日志文件路径在PicGo的设置界面里可以直接打开。日志信息非常关键。很多人反馈说“只显示上传失败没有详细原因”其实是因为日志级别太低或者看的是通知栏提示而不是日志文件。真正的错误原因基本都会在日志里体现比如HTTP状态码、返回的JSON内容。排查的时候建议把PicGo里原来填的仓库名、分支名、Token这三项全部清空重新填一遍。我遇到过好几次配置看起来没错但不是末尾多了个空格就是Token复制进来的时候带了换行符。重新手动填一遍很多奇怪问题就消失了。4. 典型错误讯息速查表为了让你不再和我当初一样一遍遍翻帖子我这里整理了一个错误速查表。遇到报错的时候直接对照着看比瞎试高效得多。错误现象可能原因处理办法上传失败:网络请求错误网络不通、DNS异常、防火墙拦截、系统时间不准先执行 curl 验证连通性检查系统时间是否为自动同步排查本地安全类软件Authentication failed / 认证失败Token过期、Token格式错误、权限不足重新生成Token勾选repo或配置Fine-grained权限404 Not Found仓库名格式错误、分支名错误、仓库不存在确认仓库名是“用户名/仓库名”用仓库页面实际默认分支替换配置422 Unprocessable Entity同名文件已存在、文件内容无变化开启PicGo时间戳重命名或改用其他文件名403 rate limit exceededGitHub API请求次数超限等待限流窗口过后再试或减少上传频率图片链接打不开但上传提示成功自定义域名配置错误、路径拼接错误检查自定义域名格式确认链接URL的路径是否正确上传大文件失败文件超过GitHub单文件100MB限制压缩图片到1MB以内再上传提示上传成功但服务器返回错误返回的链接指向了API地址而非raw地址检查自定义域名确认链接使用的协议和域名正确4.1 “上传失败:网络请求错误”细说这可能是遇到最多的报错。字面意思是PicGo向GitHub发送请求时网络层面出了问题但它背后的原因可以有很多层第一层真的是网络断连。检查能不能正常打开其他网站。 第二层DNS解析失败。GitHub域名解析不到IP请求发不出去。 第三层SSL证书校验失败。这往往是因为本机系统时间不准确导致证书有效期验证不通过。你可能会奇怪系统时间怎么会错但虚拟机和长期没关机的老电脑经常出现这种问题。 第四层本地防火墙或安全类软件拦截了PicGo进程的对外通信。尤其Windows平台有时候杀毒软件会静默阻止新安装的软件联网。排查思路就是先分层确认每层都通了再收窄范围。最怕的是跳过排查反复卸载重装PicGo那样只是浪费时间。4.2 “提示上传成功却拿不到链接”的假成功还有一种情况比报错更气人PicGo明明提示上传成功你复制出链接一访问却是404。这种一般不是网络问题而是链接拼接问题。PicGo在上传成功后会根据“自定义域名 用户名 仓库名 分支 路径”拼接出图片链接。如果你自定义域名填的格式不对比如填成了仓库API地址或者填成了不带协议头的裸域名最终就会生成一个错误的链接。解决办法是把自定义域名统一改成标准格式https://raw.githubusercontent.com然后手动用下面的规则拼一次链接测试https://raw.githubusercontent.com/{用户名}/{仓库名}/{分支}/{存储路径}/{图片文件名}在浏览器里能打开再回PicGo里对比一下它生成的链接差异一眼就能看出来。5. 让GitHub图床更稳定的几个经验排查完问题图床恢复了正常使用但这不意味着故事就结束了。我用了三年多的GitHub图床中间踩了无数坑这里挑几个最值得说的经验分享给你。5.1 命名习惯决定了你在给自己挖不挖坑如果你没有开启PicGo的时间戳重命名那两张同名图片第二次上传时就会触发422错误。开启方式很简单PicGo设置 - 时间戳重命名打开开关。这样文件名会自动带上毫秒级时间戳基本不会重复。另外一个建议是上传前先把图片压缩一遍。截图工具的默认输出往往非常庞大一张屏幕截图轻松超过2MB而GitHub单个文件超过100MB才会拒绝但仓库整体容量建议控制在1GB以下。图片动辄几百KB甚至几MB用不了多少张仓库就膨胀到令人崩溃。我现在写文档前都会用工具把图片压到200KB以内肉眼基本无差别但仓库和访问速度都能轻松不少。5.2 不要把鸡蛋都放在一个图床上我见过有人把整个博客的图片都只放在GitHub图床上结果某一天Token过期所有配置失效新图传不上去只能干着急。建议在PicGo里配置两个以上的图床。我自己的方案是GitHub为主、又拍云或七牛云作为备用。平时只要GitHub正常就用它哪天它闹脾气切换备用图床只需要在PicGo里点一下完全不影响写文章节奏。如果你只想用GitHub至少也应该把Token的过期日期记在待办事项里到期前主动重新生成免得在深夜赶文时被打个措手不及。5.3 定期清理和备份图床仓库也是需要维护的。如果你长期传图仓库里的图片文件会越来越多文件多了之后本地clone仓库会越来越慢GitHub API的访问速度也会受到影响。我会每半年做一次清理把仓库clone下来删除不再使用的图片同时把重要的图片文件同步到本地备份盘或者另一个私有仓库。GitHub虽然稳定性好但任何服务都有不可控的因素重要数据永远要有第二份。平时用起来省心都是因为维护做在了前面。6. 从问题到常态一个可复用的检查脚本排查了这么多次我把经验沉淀成了一个固定流程。每次改图床配置或者遇到上传失败时按顺序跑一遍基本10分钟内定位问题。打开浏览器访问https://github.com确认本机网络正常。执行curl -I https://api.github.com确认API可访问。执行curl -H Authorization: token 你的Token https://api.github.com/user确认Token有效。打开PicGo设置核对仓库名格式、分支名、Token、存储路径、自定义域名。上传一张测试图复制链接在浏览器打开确认最终访问正常。每一步都不复杂但它能快速告诉你问题出在哪一层。我做了一张流程图挂在笔记里每次出问题就照着走再也没因为图床问题折腾超过半小时。你可能觉得这套流程听起来简单但我踩过的坑一点都不简单。第一次遇到分支名填错我研究了半天API文档第一次Token过期我还以为电脑中了毒。这些看起来很蠢的错误在没有头绪的时候真的能折磨人一整晚。配置GitHub图床这件事说穿了就是几项配置的组合游戏但每一个小细节都有可能成为拦路虎。把链路理顺、把规则搞懂再遇到报错的时候你就能一眼看穿它。