如果你和我一樣習(xí)慣用 Typora 寫 Markdown 筆記那你一定遇到過這種尷尬文章里貼了十幾張截圖本地打開一切正常一旦復(fù)制到博客后臺或者發(fā)給同事圖片全部裂開。問題不在 Typora而在于 Markdown 里的圖片引用本質(zhì)是一個路徑問題本地路徑一旦離開本機就失效。Typora PicGo Gitee碼云這套組合就是為了解決路徑斷裂而生Typora 負(fù)責(zé)寫作PicGo 負(fù)責(zé)把圖片傳到 Gitee 倉庫Gitee 返回一個公開可訪問的圖片直鏈Markdown 里引用這個直鏈文章放到任何平臺都能正常顯示。這套方案適合所有用 Markdown 寫作的人——寫技術(shù)博客、做學(xué)習(xí)筆記、沉淀團隊文檔都適用花十幾分鐘配置一次后面能省下大量改圖時間。1. 先搞清楚Markdown 圖片到底卡在哪一環(huán)1.1 一張圖片在 Markdown 里的完整旅程很多人第一次遇到圖片失效時第一反應(yīng)是換博客平臺結(jié)果換了一圈問題依舊。Markdown 里的圖片語法是這個地址可以是一個本地相對路徑也可以是一個完整網(wǎng)址。當(dāng)你在本地用 Typora 寫筆記時它默認(rèn)會把截圖保存到某個文件夾并在文檔里填入./assets/xxx.png這樣的相對路徑。Typora 自己能解析是因為圖片文件就在你電腦里一旦文檔被復(fù)制到線上平臺、在線文檔或者同事的電腦這個相對路徑對應(yīng)的文件夾并不存在圖片自然裂開。換句話說Markdown 圖片失效的本質(zhì)是引用關(guān)系被打破。要讓圖片在任何地方都能展示唯一可靠的思路是把圖片放到一個所有終端都能訪問的公共空間然后用一個絕對的網(wǎng)絡(luò)地址去引用。這個公共空間就是圖床。理解了這一點后續(xù)所有配置都圍繞同一件事展開把本地文件移動到遠(yuǎn)端并拿回一個通用鏈接。1.2 本地管理和圖床管理的本質(zhì)區(qū)別本地管理圖片你得到的是一個個.png、.jpg文件夾文件歸自己掌控缺點是文檔一挪窩就失效。圖床管理圖片你得到的是一個 URL文件不在手邊但任何連接網(wǎng)絡(luò)的設(shè)備都能打開。兩者各有利弊關(guān)鍵看你要文檔“能跑得遠(yuǎn)”還是“文件一定在自己手里”。維度本地文件夾圖床Gitee分享便利性低必須帶著文件夾一起傳高復(fù)制 URL 即可成本零成本免費額度即可起步維護負(fù)擔(dān)需要手動遷移、打包基本零維護穩(wěn)定性硬盤損壞、誤刪即丟失依賴平臺穩(wěn)定性和使用規(guī)則適用場景永遠(yuǎn)只在本地看的私密筆記博客、文檔、協(xié)作、公開分享如果你寫的東西只在本地自己看本地路徑完全沒問題但只要存在任何一次跨設(shè)備、跨平臺的分發(fā)需求圖床就是繞不開的選擇。很多人的誤區(qū)是把“本地備份”和“圖床”對立起來其實它們可以共存圖床負(fù)責(zé)對外鏈接的穩(wěn)定訪問本地依舊保留原圖作為備份這樣兩邊的好處都拿到了。1.3 一套圖床方案的完整工作鏈路動手之前先把鏈路理清。你在 Typora 里拖入一張截圖Typora 并不會直接把圖片變成鏈接它需要一個“搬運工”PicGo 就是做這件事的。PicGo 啟動后會在本地開一個小服務(wù)Typora 把本地圖片交給這個服務(wù)PicGo 再通過 Gitee 的開放接口把圖片傳到你預(yù)先建好的倉庫拿到一個圖片直鏈最后 Typora 自動把 Markdown 里的本地路徑替換成這個網(wǎng)絡(luò)鏈接。整個流程只有三步本地圖片出現(xiàn) - PicGo 上傳到 Gitee 倉庫 - Typora 拿到鏈接并寫進文檔。鏈路聽起來很簡單但每個環(huán)節(jié)都有一些容易踩坑的細(xì)節(jié)尤其是令牌權(quán)限、倉庫可見性、分支名這些配置往往“一步錯全盤錯”。后面我會按搭建順序逐個說明這也是我第一次配置時反復(fù)折騰后總結(jié)出的最穩(wěn)妥路徑。2. 工具選型為什么是 Typora PicGo Gitee 這一套2.1 Typora 把寫作體驗和圖片處理一體化Markdown 編輯器有很多Typora 能被大量用戶當(dāng)作主力核心原因是“所見即所得”輸入 Markdown 語法界面直接渲染成排版后的效果不需要同時開兩個窗口。這聽起來不算什么優(yōu)勢但對每天寫字的人來說沉浸感差別很大。真正讓 Typora 適合做圖床集成的是它在偏好設(shè)置里提供了完整的圖片上傳配置。你可以把“插入圖片時的默認(rèn)動作”直接設(shè)為“上傳圖片”還可以選擇一個圖床客戶端作為上傳服務(wù)。這意味著你不需要每張圖都手動操作只要把圖拖進編輯器后續(xù)的一切都是自動的。對比之下很多編輯器要么需要自己寫插件要么只能手動復(fù)制圖片地址體驗差距就在這里體現(xiàn)出來。2.2 PicGo 把“上傳”變成一次看不見的操作PicGo 是一個開源圖床客戶端它的核心價值是把“上傳圖片”這個動作從打開網(wǎng)頁、選擇文件、點擊上傳、復(fù)制鏈接這四五步壓縮成一次右鍵菜單或自動調(diào)用。PicGo 支持多種圖床默認(rèn)界面里內(nèi)置了部分常見圖床但 Gitee 并不在列表里需要安裝社區(qū)插件 gitee-uploader 才能啟用。安裝完之后PicGo 左側(cè)會出現(xiàn)“碼云”相關(guān)入口。這個插件上傳圖片的原理是調(diào)用 Gitee 的“創(chuàng)建文件”接口每一次上傳本質(zhì)上都是往你的 Gitee 倉庫提交一個新文件和你在網(wǎng)頁上上傳一個文件沒有區(qū)別只是交給了 API 去做。明白了這個原理后面很多報錯就能看懂——既然本質(zhì)是提交文件到代碼倉庫那么倉庫存在與否、分支存在與否、令牌有沒有寫權(quán)限都會直接影響成敗。2.3 Gitee 做圖床的甜與苦選擇 Gitee最直接的動機是免費、國內(nèi)環(huán)境下載速度快、注冊門檻低。很多主流的對象存儲服務(wù)需要實名、付費甚至要動態(tài)綁定云賬號對只想好好寫筆記的人來說太重了。Gitee 就是一個代碼托管平臺注冊之后建倉庫就能用圖片上傳走的是普通倉庫接口成本幾乎為零。但它畢竟不是專門做圖床的有幾個問題必須正視。第一倉庫容量有限制圖片是二進制文件一張截圖幾百 KB幾萬張下來很容易把倉庫撐大平臺對倉庫體積過大會有提示。第二Gitee 倉庫內(nèi)容需要符合平臺規(guī)則圖片倉庫如果被判定為純圖床用途存在被限制或要求刪除的風(fēng)險。第三外鏈的穩(wěn)定性不如專業(yè)對象存儲圖片放在 Gitee 上哪天平臺調(diào)整防盜鏈策略歷史圖片可能大面積受影響?；谶@些原因我的建議是把它定位成“個人寫作初期的免費圖床”重要圖片一定要在本地留備份別把唯一副本交給任何免費服務(wù)。2.4 其他圖床方案的對比參考如果你已經(jīng)在幾個方案之間猶豫不妨快速對比一下。常見的免費圖床方案還有 GitHub PicGo但國內(nèi)環(huán)境訪問速度波動較大國內(nèi)云廠商的對象存儲價格便宜穩(wěn)定性最高但首次配置稍微復(fù)雜有些極簡圖床網(wǎng)站只支持手動上傳無法和 Typora 聯(lián)動不適合批量寫作。Gitee 方案最大的優(yōu)勢是“國內(nèi)訪問快 API 開放 免費”最大的劣勢是容量限制和規(guī)則不確定性。這套組合適合作寫作者的入門方案等圖片量真正上來后再考慮云存儲也算一條平滑的升級路徑。3. 從零搭建Gitee 倉庫、私人令牌、PicGo 聯(lián)動3.1 建倉庫前先想清楚的 4 個設(shè)置第一步是去 Gitee 新建倉庫。倉庫名稱可以按照個人習(xí)慣來比如markdown-images、picgo-bed只要能看懂用途就行。建倉庫時有幾個選項如果不注意后面會踩坑。倉庫必須選擇開源。這是很多人最容易忽略的一點。PicGo 上傳圖片后Markdown 里引用的是鏈接如果你的倉庫是私有的訪問鏈接需要登錄和權(quán)限別人打開你的文章依然是裂圖。如果你確實有一些圖片不想公開就不應(yīng)該放圖床別試圖用私有倉庫來兼顧私密那樣做圖床就失去了意義。初始化設(shè)置建議勾選“使用 Readme 文件初始化倉庫”。如果建一個完全空白的倉庫倉庫就沒有默認(rèn)分支PicGo 調(diào)用接口時找不到可在哪個分支提交文件容易報分支不存在。先初始化出一個 README等于給倉庫確定了一個默認(rèn)分支PicGo 里填的分支名才能對應(yīng)上。順便在初始化完成后去倉庫頁面確認(rèn)一下默認(rèn)分支到底是master還是main不同時期創(chuàng)建的倉庫可能不同記下這個分支名后面要用。最后是倉庫描述隨便填一個可見用途說明就好。Gitee 對倉庫的“項目描述”可能會有校驗尤其當(dāng)倉庫是圖床用途時描述越明確越不容易被誤判。3.2 私人令牌最容易忽視的一環(huán)Gitee 不像某些平臺允許直接用賬號密碼做 API 鑒權(quán)它要求使用私人令牌也就是 Personal Access Token。這是整個配置里最需要留意的部分。生成位置在 Gitee 網(wǎng)頁端進入個人設(shè)置 - 安全設(shè)置 - 私人令牌點擊生成新令牌。生成時會讓填寫令牌描述比如typora-picgo方便日后認(rèn)出來。關(guān)鍵是權(quán)限范圍的選擇我測試下來至少要勾選與 projects 相關(guān)的讀寫權(quán)限。Gitee 的權(quán)限界面偶爾會更新如果你不確定就優(yōu)先把“projects”相關(guān)的讀、寫權(quán)限都勾上不要只勾只讀否則上傳會被拒。令牌生成后頁面只會完整顯示一次關(guān)閉頁面就再也看不到了。我第一回沒當(dāng)回事復(fù)制完順手關(guān)掉后來換電腦要重新填只能重新生成一個再配一遍。正確的做法是生成后立刻存到密碼管理器里或先在本地記錄一份再操作。令牌相當(dāng)于你賬號在某些接口操作下的密碼千萬別把它直接提交到公開倉庫泄露了就去令牌列表里刪除重建不要抱著僥幸心理繼續(xù)用。3.3 PicGo 安裝 gitee-uploader 插件與參數(shù)逐項填寫下載安裝 PicGo 客戶端后第一次打開先別急著配任何參數(shù)去“插件設(shè)置”頁面搜索gitee-uploader找到后安裝。安裝完成后左側(cè)欄會多出“碼云”或類似命名的一欄點進去才是真正的配置界面。填參數(shù)時最核心的是這幾項。repo必須填用戶名/倉庫名這種完整格式比如你 Gitee 用戶名是zhangsan倉庫名是markdown-images就填zhangsan/markdown-images。注意不是只填倉庫名很多人第一次在這里報錯。branch填倉庫默認(rèn)分支名就是剛才讓你記下來的那個是master就填master是main就填main。token填入剛才保存的私人令牌建議直接粘貼并檢查有沒有多余空格。path項表示圖片上傳到倉庫后的目錄前綴我習(xí)慣填img/這樣所有圖片都收在倉庫的 img 目錄下倉庫本身不會亂。customPath是動態(tài)子目錄默認(rèn)可以留空也可以按需配置年/月日之類。customURL一般留空讓插件自己拼接 Gitee raw 鏈接。保存后先去 PicGo 主界面拖入一張測試圖片選擇碼云上傳。如果返回了一個 URL說明 Gitee 端的配置已經(jīng)通了可以進入下一步。3.4 上傳成功后才算真正的第一步有的朋友填完參數(shù)不測試就直接去 Typora 里配置結(jié)果上傳失敗一下子分不清是 PicGo 的問題還是 Typora 的問題。所以務(wù)必在 PicGo 單獨跑通一次測試。測試圖片選一張小圖就行如果上傳成功去 Gitee 倉庫的img目錄下能看到這個文件同時 PicGo 日志窗口會顯示上傳成功和返回的 URL 鏈接。這一步能確認(rèn)的倉庫地址沒問題、分支沒問題、令牌權(quán)限沒問題、插件配置沒寫錯。排除這些變量之后再去配 Typora萬一后面出問題排查范圍就縮小很多。這也是我調(diào)試這類工具鏈的習(xí)慣逐層驗證不要搭好一整條鏈路再去猜 bug。4. Typora 對接 PicGo配置完成后全程無感4.1 圖片偏好設(shè)置里的關(guān)鍵選項打開 Typora 的偏好設(shè)置找到“圖像”分類。這里有三個關(guān)鍵設(shè)置插入圖片時的默認(rèn)動作、上傳服務(wù)提供商、PicGo 可執(zhí)行文件路徑?！安迦雸D片時”這一項要選擇“上傳圖片”。注意這個選項的意思是你每拖入一張圖片Typora 會直接走上傳流程如果你還希望本地保留原圖可以在文件層面自己留一份不影響 Typora 的上傳行為。上傳服務(wù)選擇PicGo(app)然后在下面指定 PicGo 的安裝路徑。Windows 上一般是安裝目錄里的PicGo.exemacOS 上需要找到.app包路徑命令行工具則要定位到picgo可執(zhí)行文件。如果路徑?jīng)]填對Typora 會提示找不到應(yīng)用這時先去文件管理器里確認(rèn)你的 PicGo 到底裝在哪里。還有個容易被忽略的點Typora 通過本地接口調(diào)用 PicGo 時PicGo 必須已經(jīng)在后臺運行。很多人的習(xí)慣是寫完文檔順手退出 PicGo之后再寫新文檔上傳圖片就會失敗因為 Typora 調(diào)用不到那個本地服務(wù)。建議把 PicGo 設(shè)置為開機自啟讓它一直駐留在系統(tǒng)托盤里寫作時就不用再想這件事。4.2 第一次驗證“粘貼即上傳”配置完成后新建一個測試文檔拖入一張圖片。正常情況下圖片會從本地路徑自動變成一個完整的網(wǎng)絡(luò)鏈接。判斷它是否真的成功不要只看 Typora 界面里圖片是否還顯示因為 Typora 有本地緩存就算鏈接是壞的它也可能顯示給你看。更可靠的驗證方式是去 Gitee 倉庫刷新頁面看img目錄下是否出現(xiàn)這個新圖片文件或者直接打開 PicGo 的上傳日志日志里會顯示上傳結(jié)果和返回的 URL。如果拖入圖片后 Typora 里還是本地相對路徑多半是“插入圖片時”沒有設(shè)為“上傳圖片”或者沒勾選下方對現(xiàn)有圖片應(yīng)用該規(guī)則。如果有舊文章里已經(jīng)插入了大量本地圖片可以后續(xù)統(tǒng)一處理但對于新建文檔務(wù)必保證默認(rèn)行為就是上傳。4.3 圖片鏈接格式與常見誤解上傳成功后Typora 里生成的鏈接長這樣這里的關(guān)鍵是raw字段它表示返回的是原始文件內(nèi)容而不是倉庫的文件頁面。很多人誤把倉庫的文件網(wǎng)頁地址當(dāng)成圖片鏈接那種地址打開是網(wǎng)頁不是圖片放進 Markdown 后也無法被正常渲染。你只需要記住圖片鏈接的路徑里一定要包含raw這是 Gitee 圖床能用的前提。另外圖片文件名最好不要帶中文。雖然 Gitee 的 raw 鏈接在某些情況下能處理中文但不少平臺在解析中文 URL 時會出問題還有可能被轉(zhuǎn)成百分號編碼導(dǎo)致某些 Markdown 渲染器無法識別。PicGo 上傳時如果有開啟時間戳重命名等功能文件名會自動變成數(shù)字串這是最省事的做法如果你習(xí)慣自己截圖后手動命名盡量用英文字母和數(shù)字。4.4 剪貼板鏈接還有一個附加用途Typora 集成只是圖床的一個出口PicGo 本身也是一個獨立的上傳工具。比如你在寫匯報、做幻燈片時需要把某張圖快速放到一個在線文檔里可以不用打開網(wǎng)頁直接在 PicGo 拖入圖片它會把 Markdown 格式的鏈接自動復(fù)制到剪貼板你粘貼到哪里都能用。在 PicGo 設(shè)置里可以把默認(rèn)鏈接格式改為 Markdown、URL 或 HTML按使用場景取舍。這一點往往被教程忽略但對日常辦公來說非常實用。我經(jīng)常在微信對話、在線表單里需要臨時貼圖打開 PicGo 拖圖進去然后粘貼鏈接整個流程不超過五秒比打開圖床網(wǎng)頁慢慢傳要快得多。5. 常見問題排查看這里我踩過的坑都在這些5.1 上傳失敗時先看日志不要反復(fù)重試PicGo 的“上傳日志”標(biāo)簽頁絕不是擺設(shè)。凡是上傳失敗日志里都會給出具體錯誤碼或錯誤信息排查的第一步必須是這里。很多人失敗后選擇反復(fù)重新上傳結(jié)果只在日志里刷出一排同樣的錯誤純屬浪費時間。正確的姿勢是把日志里的錯誤信息復(fù)制下來對照錯誤碼去定位。例如日志提示401基本可以確定是令牌問題。要么是令牌內(nèi)容被復(fù)制多了一個空格或多個字符要么是令牌權(quán)限沒有勾選寫權(quán)限。建議回到令牌列表重新生成一個新的粘貼時注意不要帶換行符。如果提示403通常也是令牌權(quán)限不足重點檢查 projects 相關(guān)權(quán)限中的寫入權(quán)限。如果是422這類參數(shù)類錯誤問題大概率出在倉庫分支或者路徑上。打開倉庫頁面確認(rèn)默認(rèn)分支究竟是master還是main再對照 PicGo 里填的內(nèi)容一個字都不能差。倉庫如果是空的而且沒有初始化 README同樣可能出現(xiàn)分支不存在的報錯先去倉庫里提交一個 README 文件讓分支存在然后再試。5.2 圖片裂開不一定是上傳失敗有時日志顯示上傳成功Typora 里也有網(wǎng)絡(luò)鏈接但文章發(fā)布到某個平臺后圖片還是裂的。此時要區(qū)分兩種情況。第一種是鏈接本身有問題例如不是raw鏈接第二種是目標(biāo)平臺主動屏蔽了外部圖片很多博客平臺、公眾號編輯器都有防盜鏈機制不加載來自外部域名的圖片。如果是第二種這是 Gitee 免費圖床的天然局限靠配置解決不了。常見的對策有三個換一個允許外鏈的平臺發(fā)布用支持圖片轉(zhuǎn)存功能的寫作工具或者干脆把圖床升級為帶獨立域名訪問的對象存儲。免費方案能解決的問題有邊界圖片量上來之后該花的成本還是得花。5.3 Gitee 倉庫體積和平臺限制的應(yīng)對思路Gitee 倉庫有容量限制圖片文件又屬于比較快速的體積增長類型。用過一段時間后你會發(fā)現(xiàn)倉庫體積漲得比想象中快因為每一張截圖少說幾十 KB多則幾 MB。這也意味著不能把 Gitee 當(dāng)永久倉庫來用得有點規(guī)劃。我常用的做法是“圖片瘦身”截圖工具保存的 PNG 文件很大上傳前用壓縮工具轉(zhuǎn)成 JPEG 或 WebP畫質(zhì)損失不大體積能減少一半以上。另一個辦法是按時間段整理倉庫比如每年建一個圖床倉庫避免一個倉庫無限膨脹。更重要的是原圖一定要在本地或網(wǎng)盤里留一份圖床里存的只是對外分發(fā)的那份副本。5.4 換了電腦配置怎么快速恢復(fù)圖床配置說多不多但重新填起來也麻煩尤其是 Gitee 倉庫名、分支、令牌這些細(xì)節(jié)時間一長很容易記混。PicGo 的配置其實都保存在本地數(shù)據(jù)文件里我習(xí)慣在配置穩(wěn)定后直接把整個 PicGo 數(shù)據(jù)文件備份一份到網(wǎng)盤。換電腦時裝上同樣的 PicGo 版本再用備份文件覆蓋回去所有圖床配置一次恢復(fù)不需要重新走一遍全套填參數(shù)流程。如果你不打算備份配置文件那至少要把令牌存到密碼管理器里倉庫名和分支名記到筆記里。不要臨時去翻網(wǎng)頁更不要在聊天記錄里找令牌那樣既低效也安全風(fēng)險很高。5.5 雜項問題速查表現(xiàn)象可能原因處理建議Typora 提示無法連接 PicGoPicGo 未運行或路徑填錯啟動 PicGo確認(rèn)后臺托盤圖標(biāo)存在上傳后鏈接打開是網(wǎng)頁不是圖片缺少raw檢查鏈接格式改為 raw 直鏈圖片在博客后臺不顯示目標(biāo)平臺外鏈屏蔽換平臺或換圖床上傳速度很慢圖片太大或網(wǎng)絡(luò)波動先壓縮圖片再重試倉庫里圖片目錄很亂未設(shè)置 path在 PicGo 插件里統(tǒng)一設(shè)置img/路徑刪除圖片后發(fā)現(xiàn)鏈接依然能訪問緩存或已提交記錄無需處理舊的 raw 引用可能保留5.6 一個心理預(yù)期層面的提醒每次有人讓我推薦圖床方案我都會先說一句免費方案要做好“隨時可能失效”的心理準(zhǔn)備。Gitee 不是專門做圖床的平臺它隨時可能調(diào)整規(guī)則倉庫也可能因為觸發(fā)限制被要求整改。圖床可以免費你的重要圖片不能沒有退路。所以從第一天起就應(yīng)該把圖床當(dāng)成“分發(fā)加速層”而不是“唯一邊界”。原圖備份的習(xí)慣遠(yuǎn)比圖床本身重要。我用這套方案寫了很長一段時間從本地筆記到線上博客再到跨設(shè)備協(xié)作圖片再也沒有成為阻礙。最深的體會是好的工具鏈不是讓你多做什么而是讓你少操心。Typora、PicGo、Gitee 這三者單獨拿出來都很簡單組合在一起才真正解決了 Markdown 寫作者的痛點。配置過程中你會遇到一兩次報錯照著日志排查基本十分鐘內(nèi)都能解決。最后再分享一個小習(xí)慣每次給圖片倉庫瘦身后我都會順手在倉庫首頁寫一條更新說明記錄這次清理壓縮了哪些內(nèi)容、遷移了多少圖片。等倉庫體積再次接近限制時回看記錄就能快速定位到可遷移的文件不用翻著文件列表懵圈。這套流程跑順之后你會覺得當(dāng)初那十幾分鐘配置時間花得相當(dāng)值。