前兩天想給一篇技術(shù)筆記配圖截圖之后順手按下快捷鍵PicGo彈了個(gè)通知說上傳成功。我心想還挺順結(jié)果往文章里粘貼鏈接的時(shí)候才發(fā)現(xiàn)圖片根本打不開?；仡^看了一眼日志里面躺著一行紅字上傳失敗:網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤 (async upload fail error: 系統(tǒng)錯(cuò)誤)。這個(gè)報(bào)錯(cuò)我太熟了。玩博客、寫文檔、搭個(gè)人站的人只要用的是PicGo GitHub 圖床這套組合幾乎都撞過類似的墻。明明配置填了好幾遍Token也復(fù)制了倉(cāng)庫(kù)名也對(duì)得上可圖片就是傳不上去。這篇文章不打算講什么高深原理就是把“PicGo上傳圖片到Github倉(cāng)庫(kù)上傳失敗”這個(gè)場(chǎng)景徹底拆開從上傳鏈路、配置項(xiàng)、網(wǎng)絡(luò)環(huán)境、Token權(quán)限、分支名、文件大小這些最容易被忽略的環(huán)節(jié)一步一步帶你排查到底。無論你是剛配好圖床的新手還是已經(jīng)踩過幾次坑的老手照著這篇文章走一遍基本能找到問題根源。1. 先看懂PicGoGitHub圖床的上傳鏈路很多人一看到“網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤”就把鍋甩給PicGo覺得是軟件壞了。其實(shí)不是。PicGo本身只是一個(gè)客戶端真正干活的是GitHub的API。想排查問題得先搞清楚一條圖片從剪貼板到倉(cāng)庫(kù)到底經(jīng)過了哪些環(huán)節(jié)。1.1 一次上傳背后到底發(fā)生了什么PicGo上傳圖片到GitHub本質(zhì)上就三步你把截圖復(fù)制到剪貼板PicGo讀取剪貼板里的圖片數(shù)據(jù)。PicGo把圖片二進(jìn)制內(nèi)容轉(zhuǎn)成Base64然后調(diào)用GitHub的contentsAPI向https://api.github.com/repos/{用戶名}/{倉(cāng)庫(kù)名}/contents/{路徑}發(fā)送一個(gè)PUT請(qǐng)求。GitHub API收到請(qǐng)求校驗(yàn)Token權(quán)限把圖片文件寫入對(duì)應(yīng)倉(cāng)庫(kù)分支然后返回一個(gè)包含文件信息的JSON響應(yīng)。PicGo拿到響應(yīng)之后組合出圖片的訪問鏈接例如https://raw.githubusercontent.com/{用戶名}/{倉(cāng)庫(kù)名}/{分支}/{路徑}再?gòu)?fù)制到你的剪貼板里。所以如果鏈路中任何一環(huán)出了問題你看到的報(bào)錯(cuò)內(nèi)容會(huì)完全不一樣。比如Token帶錯(cuò)返回的是401認(rèn)證失敗倉(cāng)庫(kù)名填錯(cuò)返回404文件同名沖突返回422網(wǎng)絡(luò)出問題則可能直接是“網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤”。理解了這條鏈路排查就不會(huì)像無頭蒼蠅一樣亂試。1.2 失敗消息怎么歸類觀察實(shí)際遇到的報(bào)錯(cuò)大致可以分成三類配置類錯(cuò)誤倉(cāng)庫(kù)名寫錯(cuò)、分支名寫錯(cuò)、Token缺失或權(quán)限不足。這類報(bào)錯(cuò)通常來自GitHub的明確響應(yīng)比如Authentication failed、404 Not Found、422等。網(wǎng)絡(luò)類錯(cuò)誤請(qǐng)求沒到達(dá)GitHub或者響應(yīng)沒回來。常見的就是“網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤”“系統(tǒng)錯(cuò)誤”“timeout”也有不少情況是DNS解析失敗、防火墻攔截、系統(tǒng)時(shí)間不準(zhǔn)確導(dǎo)致的SSL握手失敗。資源類錯(cuò)誤文件名沖突、文件太大超過GitHub限制、倉(cāng)庫(kù)容量超限、API限流。這類錯(cuò)誤往往在配置完全正確的狀態(tài)下出現(xiàn)非常容易被忽略。我個(gè)人習(xí)慣是先判斷報(bào)錯(cuò)字符串屬于哪一類再?zèng)Q定從哪個(gè)方向查。否則一上來就刪Token重新生成折騰半天發(fā)現(xiàn)白忙一場(chǎng)。2. 配置核查多數(shù)失敗都栽在不起眼的地方很多“上傳失敗”其實(shí)不是網(wǎng)絡(luò)問題而是配置項(xiàng)里藏著雷。下面這幾個(gè)配置點(diǎn)是我見過最高頻的“翻車現(xiàn)場(chǎng)”。2.1 Token的權(quán)限與有效期GitHub Token是訪問倉(cāng)庫(kù)的鑰匙也是最容易出錯(cuò)的地方。如果你用的是Classic Token生成時(shí)一定要勾選repo權(quán)限這是個(gè)合集權(quán)限包含倉(cāng)庫(kù)內(nèi)容的讀寫。只勾了read:user或者干脆沒勾權(quán)限PicGo上傳時(shí)就會(huì)收到403或者401。如果你用的是Fine-grained Token就要更小心。這類Token默認(rèn)沒有倉(cāng)庫(kù)權(quán)限需要在Repository access里選擇All repositories或者Only select repositories然后在Permissions里把Contents設(shè)為Read and write。很多人生成的時(shí)候隨手選了只讀結(jié)果上傳必定失敗。另外Token的過期時(shí)間也是個(gè)隱形坑。GitHub現(xiàn)在生成的Token默認(rèn)會(huì)設(shè)置有效期常見的是7天、30天、90天。過期之后PicGo不會(huì)給你任何“Token過期”的明確提示只會(huì)表現(xiàn)為上傳失敗日志里寫著認(rèn)證錯(cuò)誤或者網(wǎng)絡(luò)錯(cuò)誤。如果你已經(jīng)很久沒有重新生成過Token那大概率是它悄悄失效了。2.2 倉(cāng)庫(kù)名和分支名格式PicGo設(shè)置里的“倉(cāng)庫(kù)名”并不是隨便填個(gè)名字就行格式必須是用戶名/倉(cāng)庫(kù)名。比如你的GitHub用戶名是zhangsan倉(cāng)庫(kù)是blog-images那就填zhangsan/blog-images少一個(gè)部分或者多一個(gè)空格都會(huì)觸發(fā)404。分支名更是個(gè)大坑。早些年GitHub默認(rèn)分支是master而現(xiàn)在新建的倉(cāng)庫(kù)默認(rèn)是main。如果你在PicGo里填的分支名和倉(cāng)庫(kù)實(shí)際默認(rèn)分支不一致請(qǐng)求就會(huì)落到一個(gè)不存在的分支上結(jié)果當(dāng)然還是404。檢查方法很簡(jiǎn)單打開倉(cāng)庫(kù)頁(yè)面看左上角的分支下拉框默認(rèn)顯示的是什么PicGo里就填什么。提示分支名不要憑記憶填一定要去倉(cāng)庫(kù)頁(yè)面確認(rèn)。很多老倉(cāng)庫(kù)從master改成main之后圖床配置里的分支名還停留在過去。2.3 存儲(chǔ)路徑與自定義域名“存儲(chǔ)路徑”指的是圖片在倉(cāng)庫(kù)里的目錄前綴比如填img/圖片就會(huì)傳到倉(cāng)庫(kù)的img目錄下。這個(gè)字段可填可不填但如果你填了要留意路徑末尾是否帶斜杠以及拼寫是否正確。目錄不存在時(shí)GitHub API會(huì)自動(dòng)創(chuàng)建所以路徑本身不會(huì)導(dǎo)致失敗但會(huì)影響最終圖片鏈接的拼接?！白远x域名”這個(gè)字段大部分人填的是https://raw.githubusercontent.com然后加上用戶名、倉(cāng)庫(kù)、分支、路徑拼接出最終訪問鏈接。如果你填錯(cuò)了域名格式比如漏了https://或者路徑結(jié)構(gòu)配錯(cuò)了就會(huì)出現(xiàn)一個(gè)很迷惑的情況上傳日志顯示成功但復(fù)制出來的鏈接在瀏覽器里打不開。這種“假成功”比明確報(bào)錯(cuò)更難排查。所以我建議配置完圖床后先不要急著寫文章先手動(dòng)上傳一張測(cè)試圖復(fù)制鏈接放瀏覽器里打開看看。如果鏈接能直接看到圖片說明整套鏈路是通的。3. 一步一步排查網(wǎng)絡(luò)與認(rèn)證問題如果配置項(xiàng)檢查下來都沒問題那就要開始動(dòng)手做聯(lián)調(diào)了。這里分享一套我用過很多次的排查流程每一步都能幫你縮小問題范圍。3.1 先用命令行獨(dú)立驗(yàn)證連通性排除PicGo自身因素的影響先確認(rèn)你的電腦能不能正常訪問GitHub相關(guān)服務(wù)。打開終端執(zhí)行下面這條命令curl -I https://api.github.com如果返回了HTTP/2 200說明本機(jī)到GitHub API這一段的網(wǎng)絡(luò)是通的。再試一下raw文件服務(wù)的連通性curl -I https://raw.githubusercontent.com如果你連這兩條命令都不通或者一直卡住沒有響應(yīng)說明問題出在本地網(wǎng)絡(luò)環(huán)境上而不是PicGo配置的問題。這時(shí)候先恢復(fù)本地網(wǎng)絡(luò)環(huán)境再回頭測(cè)試PicGo。3.2 驗(yàn)證Token是否真的有權(quán)限網(wǎng)絡(luò)通的情況下下一步就是驗(yàn)證Token本身。GitHub提供了一個(gè)接口可以查看當(dāng)前Token的用戶信息curl -H Authorization: token 你的Token https://api.github.com/user如果返回了JSON里面有l(wèi)ogin: 你的用戶名說明Token本身是有效的。如果返回401說明Token已失效或格式有問題。這還沒完Token有權(quán)限不代表對(duì)目標(biāo)倉(cāng)庫(kù)有權(quán)限。繼續(xù)執(zhí)行下面這條命令確認(rèn)Token能寫入目標(biāo)倉(cāng)庫(kù)curl -X PUT \ -H Authorization: token 你的Token \ -H Content-Type: application/json \ -d {message:test,content:dGVzdA} \ https://api.github.com/repos/你的用戶名/你的倉(cāng)庫(kù)名/contents/test.txt這條命令會(huì)在倉(cāng)庫(kù)根目錄創(chuàng)建一個(gè)內(nèi)容為test的文本文件。如果返回201和文件信息說明Token對(duì)該倉(cāng)庫(kù)的寫權(quán)限沒問題問題基本可以鎖定在PicGo配置上。如果返回403或者404那你得回去檢查Token權(quán)限或倉(cāng)庫(kù)名。注意執(zhí)行完這條命令后記得去倉(cāng)庫(kù)里把測(cè)試文件刪掉或者不要在意這個(gè)遺留文件。如果介意就跳過這一步直接在PicGo里測(cè)試上傳更快。3.3 查看PicGo日志和測(cè)試上傳PicGo自帶日志系統(tǒng)。進(jìn)入設(shè)置把日志級(jí)別調(diào)整為error重新觸發(fā)一次上傳然后去日志目錄翻最新記錄。日志文件路徑在PicGo的設(shè)置界面里可以直接打開。日志信息非常關(guān)鍵。很多人反饋說“只顯示上傳失敗沒有詳細(xì)原因”其實(shí)是因?yàn)槿罩炯?jí)別太低或者看的是通知欄提示而不是日志文件。真正的錯(cuò)誤原因基本都會(huì)在日志里體現(xiàn)比如HTTP狀態(tài)碼、返回的JSON內(nèi)容。排查的時(shí)候建議把PicGo里原來填的倉(cāng)庫(kù)名、分支名、Token這三項(xiàng)全部清空重新填一遍。我遇到過好幾次配置看起來沒錯(cuò)但不是末尾多了個(gè)空格就是Token復(fù)制進(jìn)來的時(shí)候帶了換行符。重新手動(dòng)填一遍很多奇怪問題就消失了。4. 典型錯(cuò)誤訊息速查表為了讓你不再和我當(dāng)初一樣一遍遍翻帖子我這里整理了一個(gè)錯(cuò)誤速查表。遇到報(bào)錯(cuò)的時(shí)候直接對(duì)照著看比瞎試高效得多。錯(cuò)誤現(xiàn)象可能原因處理辦法上傳失敗:網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤網(wǎng)絡(luò)不通、DNS異常、防火墻攔截、系統(tǒng)時(shí)間不準(zhǔn)先執(zhí)行 curl 驗(yàn)證連通性檢查系統(tǒng)時(shí)間是否為自動(dòng)同步排查本地安全類軟件Authentication failed / 認(rèn)證失敗Token過期、Token格式錯(cuò)誤、權(quán)限不足重新生成Token勾選repo或配置Fine-grained權(quán)限404 Not Found倉(cāng)庫(kù)名格式錯(cuò)誤、分支名錯(cuò)誤、倉(cāng)庫(kù)不存在確認(rèn)倉(cāng)庫(kù)名是“用戶名/倉(cāng)庫(kù)名”用倉(cāng)庫(kù)頁(yè)面實(shí)際默認(rèn)分支替換配置422 Unprocessable Entity同名文件已存在、文件內(nèi)容無變化開啟PicGo時(shí)間戳重命名或改用其他文件名403 rate limit exceededGitHub API請(qǐng)求次數(shù)超限等待限流窗口過后再試或減少上傳頻率圖片鏈接打不開但上傳提示成功自定義域名配置錯(cuò)誤、路徑拼接錯(cuò)誤檢查自定義域名格式確認(rèn)鏈接URL的路徑是否正確上傳大文件失敗文件超過GitHub單文件100MB限制壓縮圖片到1MB以內(nèi)再上傳提示上傳成功但服務(wù)器返回錯(cuò)誤返回的鏈接指向了API地址而非raw地址檢查自定義域名確認(rèn)鏈接使用的協(xié)議和域名正確4.1 “上傳失敗:網(wǎng)絡(luò)請(qǐng)求錯(cuò)誤”細(xì)說這可能是遇到最多的報(bào)錯(cuò)。字面意思是PicGo向GitHub發(fā)送請(qǐng)求時(shí)網(wǎng)絡(luò)層面出了問題但它背后的原因可以有很多層第一層真的是網(wǎng)絡(luò)斷連。檢查能不能正常打開其他網(wǎng)站。 第二層DNS解析失敗。GitHub域名解析不到IP請(qǐng)求發(fā)不出去。 第三層SSL證書校驗(yàn)失敗。這往往是因?yàn)楸緳C(jī)系統(tǒng)時(shí)間不準(zhǔn)確導(dǎo)致證書有效期驗(yàn)證不通過。你可能會(huì)奇怪系統(tǒng)時(shí)間怎么會(huì)錯(cuò)但虛擬機(jī)和長(zhǎng)期沒關(guān)機(jī)的老電腦經(jīng)常出現(xiàn)這種問題。 第四層本地防火墻或安全類軟件攔截了PicGo進(jìn)程的對(duì)外通信。尤其Windows平臺(tái)有時(shí)候殺毒軟件會(huì)靜默阻止新安裝的軟件聯(lián)網(wǎng)。排查思路就是先分層確認(rèn)每層都通了再收窄范圍。最怕的是跳過排查反復(fù)卸載重裝PicGo那樣只是浪費(fèi)時(shí)間。4.2 “提示上傳成功卻拿不到鏈接”的假成功還有一種情況比報(bào)錯(cuò)更氣人PicGo明明提示上傳成功你復(fù)制出鏈接一訪問卻是404。這種一般不是網(wǎng)絡(luò)問題而是鏈接拼接問題。PicGo在上傳成功后會(huì)根據(jù)“自定義域名 用戶名 倉(cāng)庫(kù)名 分支 路徑”拼接出圖片鏈接。如果你自定義域名填的格式不對(duì)比如填成了倉(cāng)庫(kù)API地址或者填成了不帶協(xié)議頭的裸域名最終就會(huì)生成一個(gè)錯(cuò)誤的鏈接。解決辦法是把自定義域名統(tǒng)一改成標(biāo)準(zhǔn)格式https://raw.githubusercontent.com然后手動(dòng)用下面的規(guī)則拼一次鏈接測(cè)試https://raw.githubusercontent.com/{用戶名}/{倉(cāng)庫(kù)名}/{分支}/{存儲(chǔ)路徑}/{圖片文件名}在瀏覽器里能打開再回PicGo里對(duì)比一下它生成的鏈接差異一眼就能看出來。5. 讓GitHub圖床更穩(wěn)定的幾個(gè)經(jīng)驗(yàn)排查完問題圖床恢復(fù)了正常使用但這不意味著故事就結(jié)束了。我用了三年多的GitHub圖床中間踩了無數(shù)坑這里挑幾個(gè)最值得說的經(jīng)驗(yàn)分享給你。5.1 命名習(xí)慣決定了你在給自己挖不挖坑如果你沒有開啟PicGo的時(shí)間戳重命名那兩張同名圖片第二次上傳時(shí)就會(huì)觸發(fā)422錯(cuò)誤。開啟方式很簡(jiǎn)單PicGo設(shè)置 - 時(shí)間戳重命名打開開關(guān)。這樣文件名會(huì)自動(dòng)帶上毫秒級(jí)時(shí)間戳基本不會(huì)重復(fù)。另外一個(gè)建議是上傳前先把圖片壓縮一遍。截圖工具的默認(rèn)輸出往往非常龐大一張屏幕截圖輕松超過2MB而GitHub單個(gè)文件超過100MB才會(huì)拒絕但倉(cāng)庫(kù)整體容量建議控制在1GB以下。圖片動(dòng)輒幾百KB甚至幾MB用不了多少?gòu)垈}(cāng)庫(kù)就膨脹到令人崩潰。我現(xiàn)在寫文檔前都會(huì)用工具把圖片壓到200KB以內(nèi)肉眼基本無差別但倉(cāng)庫(kù)和訪問速度都能輕松不少。5.2 不要把雞蛋都放在一個(gè)圖床上我見過有人把整個(gè)博客的圖片都只放在GitHub圖床上結(jié)果某一天Token過期所有配置失效新圖傳不上去只能干著急。建議在PicGo里配置兩個(gè)以上的圖床。我自己的方案是GitHub為主、又拍云或七牛云作為備用。平時(shí)只要GitHub正常就用它哪天它鬧脾氣切換備用圖床只需要在PicGo里點(diǎn)一下完全不影響寫文章節(jié)奏。如果你只想用GitHub至少也應(yīng)該把Token的過期日期記在待辦事項(xiàng)里到期前主動(dòng)重新生成免得在深夜趕文時(shí)被打個(gè)措手不及。5.3 定期清理和備份圖床倉(cāng)庫(kù)也是需要維護(hù)的。如果你長(zhǎng)期傳圖倉(cāng)庫(kù)里的圖片文件會(huì)越來越多文件多了之后本地clone倉(cāng)庫(kù)會(huì)越來越慢GitHub API的訪問速度也會(huì)受到影響。我會(huì)每半年做一次清理把倉(cāng)庫(kù)clone下來刪除不再使用的圖片同時(shí)把重要的圖片文件同步到本地備份盤或者另一個(gè)私有倉(cāng)庫(kù)。GitHub雖然穩(wěn)定性好但任何服務(wù)都有不可控的因素重要數(shù)據(jù)永遠(yuǎn)要有第二份。平時(shí)用起來省心都是因?yàn)榫S護(hù)做在了前面。6. 從問題到常態(tài)一個(gè)可復(fù)用的檢查腳本排查了這么多次我把經(jīng)驗(yàn)沉淀成了一個(gè)固定流程。每次改圖床配置或者遇到上傳失敗時(shí)按順序跑一遍基本10分鐘內(nèi)定位問題。打開瀏覽器訪問https://github.com確認(rèn)本機(jī)網(wǎng)絡(luò)正常。執(zhí)行curl -I https://api.github.com確認(rèn)API可訪問。執(zhí)行curl -H Authorization: token 你的Token https://api.github.com/user確認(rèn)Token有效。打開PicGo設(shè)置核對(duì)倉(cāng)庫(kù)名格式、分支名、Token、存儲(chǔ)路徑、自定義域名。上傳一張測(cè)試圖復(fù)制鏈接在瀏覽器打開確認(rèn)最終訪問正常。每一步都不復(fù)雜但它能快速告訴你問題出在哪一層。我做了一張流程圖掛在筆記里每次出問題就照著走再也沒因?yàn)閳D床問題折騰超過半小時(shí)。你可能覺得這套流程聽起來簡(jiǎn)單但我踩過的坑一點(diǎn)都不簡(jiǎn)單。第一次遇到分支名填錯(cuò)我研究了半天API文檔第一次Token過期我還以為電腦中了毒。這些看起來很蠢的錯(cuò)誤在沒有頭緒的時(shí)候真的能折磨人一整晚。配置GitHub圖床這件事說穿了就是幾項(xiàng)配置的組合游戲但每一個(gè)小細(xì)節(jié)都有可能成為攔路虎。把鏈路理順、把規(guī)則搞懂再遇到報(bào)錯(cuò)的時(shí)候你就能一眼看穿它。