我從2018年開始正式用 Markdown 寫博客到現(xiàn)在發(fā)布了大概三百多篇文章分發(fā)到掘金、博客園、公眾號、知乎、CSDN 這些平臺。頭半年真是踩坑踩到懷疑人生本地渲染得好好的表格粘貼進知乎就碎成渣圖片路徑用了相對路徑傳到博客園全部裂開公眾號那邊更絕代碼塊縮進整個被吃掉格式像車禍現(xiàn)場。后來我慢慢把整套流程捋順了現(xiàn)在一篇 markdown 博客從定稿到發(fā)布到四五個平臺基本控制在半小時以內(nèi)。這篇我就把整套實戰(zhàn)工作流拆開來講包括寫作環(huán)境怎么搭、核心語法怎么適配各平臺奇葩規(guī)則、圖片路徑怎么處理、哪些環(huán)節(jié)可以用腳本和工具半自動化最后附一份我自己的排查速查表。適合正在用或者準備用 Markdown 寫博客、又被多平臺發(fā)布折磨過的朋友不管你是剛上手的博客新人還是已經(jīng)寫了幾年但還在手動復(fù)制粘貼的老作者這篇應(yīng)該都能幫你省下不少時間。1. 為什么我堅持用 Markdown 寫博客1.1 從“復(fù)制粘貼排版”到“一次編寫處處分發(fā)”先說說我為什么非得用 Markdown。早期我直接在平臺的富文本編輯器里寫寫完存草稿換平臺發(fā)就得重新排版——標題大小、加粗、代碼塊、引用樣式全平臺各不相同煩得我一度不想寫博客。Markdown 最大的價值是可移植性一份純文本源稿Git 管理起來干凈可以在任何編輯器里打開也可以被任何腳本處理。它把內(nèi)容從格式里解放出來了。但必須明確一點Markdown 源稿雖然是純文本但各平臺對 Markdown 的渲染規(guī)則從來不是一套標準。GitHub 風格的 Markdown 和掘金的 Markdown 就有差異公眾號和知乎甚至還談不上原生支持。所以“一次編寫處處分發(fā)”不是免費的午餐它需要你配上一層適配邏輯。這篇文章講的其實就是這層適配邏輯怎么搭。1.2 多平臺發(fā)布的真實痛點清單我總結(jié)了一下幾乎所有 Markdown 多平臺發(fā)布的痛點就集中在五個方面換行規(guī)則不同導(dǎo)致段落間距、強制換行在不同平臺渲染結(jié)果完全不同圖片路徑依賴本地相對路徑換平臺發(fā)布就裂開表格在各平臺兼容性極差復(fù)制后列錯位、邊框丟失代碼塊的高亮語言、行號、縮進在不同平臺支持程度不一樣數(shù)學公式、Callout 這類進階語法很多平臺直接不認這五個點任何一個沒處理好發(fā)布效果都會打折扣。后面我會逐一展開說怎么解決。1.3 一條主線源文件 適配層 發(fā)布動作我在長期實踐中把工作流收斂成一條主線源文件、適配層、發(fā)布動作。源文件就是那篇 md 草稿永遠只維護一份適配層是幾個固定動作——圖片轉(zhuǎn)圖床、表格轉(zhuǎn)兼容格式、代碼塊語言標記、公式轉(zhuǎn)圖片發(fā)布動作則是把適配后的版本復(fù)制到目標平臺。這條主線聽起來很簡單但每一步都有細節(jié)。比如適配層不是每次都從頭手動做而是根據(jù)目標平臺執(zhí)行不同的“規(guī)則包”發(fā)布到掘金執(zhí)行 A 組規(guī)則發(fā)布到公眾號執(zhí)行 B 組規(guī)則。這個思路很像編譯原理里的“目標代碼生成”不同后端對應(yīng)不同指令集。理解了主線后面的實操就不是背步驟而是按需組裝。2. 寫作環(huán)境搭建編輯器、插件與目錄規(guī)劃2.1 編輯器選型Typora、VS Code、Obsidian 怎么選寫作環(huán)境是我最早折騰的事。Typora 和 VS Code 是問得最多的兩個選擇加上 Obsidian這三者覆蓋了大多數(shù)人的需求。Typora 走的是所見即所得路線寫出來的渲染效果和最終網(wǎng)頁非常接近對博客作者最直觀。我目前主用的就是 Typora理由很簡單它把 Markdown 的“所見即所得”做到了極致表格、代碼塊、圖片拖拽這些高頻操作手感很好。要說缺點它本身不管理知識庫也不適合做復(fù)雜腳本處理。VS Code 適合作者本身是程序員的情況配合 Markdown All in One、markdownlint 等插件能實現(xiàn)目錄樹、快捷鍵、格式檢查、導(dǎo)出 PDF 等能力。我可以直接在 VS Code 里寫文章順便用 Git 管理版本寫完跑腳本批量處理圖片路徑一條龍下來很順手。Obsidian 更適合把博客文章當成個人知識庫的一部分雙鏈、標簽、圖譜這些功能對長期積累內(nèi)容很有價值。但它的 Markdown 有一些私有語法發(fā)布時要注意厘清別把[[雙鏈]]的語法留在草稿里導(dǎo)致平臺發(fā)布時出現(xiàn)亂碼。編輯器核心優(yōu)勢短板適合人群Typora所見即所得、輕量不支持插件擴展內(nèi)容創(chuàng)作者、非技術(shù)博主VS Code插件生態(tài)強、可跑腳本預(yù)覽與編輯分離程序員、技術(shù)博客作者Obsidian知識管理、雙向鏈接私有語法多筆記型、長期積累的博主2.2 必裝插件與關(guān)鍵配置不管用哪個編輯器有幾個配置我建議拿到手先改。Typora 用戶在“偏好設(shè)置”里務(wù)必檢查三件事勾選“Markdown 擴展語法”里的數(shù)學公式和任務(wù)列表把圖片插入路徑設(shè)為“復(fù)制到 ./assets 文件夾”避免圖片散落桌面打開“代碼塊語法高亮”并且語言識別保持開啟VS Code 用戶我推薦直接安裝這三個插件Markdown All in One補全、目錄、快捷鍵、markdownlint格式規(guī)范檢查、Markdown Preview Enhanced高級預(yù)覽和導(dǎo)出。裝完以后寫稿時右下角就不會一直飄紅線了一些小錯誤在源頭就能攔下來。2.3 目錄結(jié)構(gòu)與草稿管理寫作目錄這一塊很多人不在意但我踩過一次大坑之后就開始嚴格執(zhí)行規(guī)范了。我的整個博客工程目錄是這樣組織的blog/ source/ 2025-01-15-markdown多平臺發(fā)布指南.md ... assets/ markdown-launch/ image-01.png image-02.png exports/ juejin/ wechat/ blog-cn/ scripts/ replace-img-path.py export-markdown.py命名規(guī)則是日期-簡短標題.mdassets 下面按文章建子目錄圖片統(tǒng)一放在這里源稿和圖片都在 Git 倉庫里管理。這樣帶來的直接好處是遷移、回滾、生成平臺定制版本都很方便不會出現(xiàn)“圖片在哪”這種靈魂拷問。如果你已經(jīng)寫了挺久但目錄亂成一鍋粥我建議找一個周末專門重構(gòu)一次長期收益非常大。3. 核心語法與格式適配最容易翻車的地方3.1 換行為什么段落總是擠在一起先講最常見也最容易被忽略的換行問題。Markdown 標準里段落之間必須用一個空行分隔否則即使寫了換行渲染時也會被合并成一段。而“行尾加兩個空格強制換行”這個規(guī)則在 Typora 里顯示正常但粘貼到掘金、知乎這類平臺兩個空格會被吃得很隨意最終效果就是行沒換、段落全擠成一坨。我的做法簡單粗暴寫正文段落時絕不在段內(nèi)使用行尾兩個空格做強制換行分段一律用空行如果確實需要短行排列比如列舉步驟每步單獨一行就使用無序列表或者有序列表而不是靠換行撐排版。這樣至少能保證大多數(shù)平臺的渲染結(jié)果和本地預(yù)覽一致。另外手機上寫協(xié)作文檔時往往習慣直接回車分段這類文本復(fù)制到博客平臺同樣會因為缺空行而黏連粘貼前最好先全局檢查一遍空行結(jié)構(gòu)。3.2 圖片路徑三步走相對路徑、圖床、CDN圖片路徑是我發(fā)布流程里最早被解決的問題。用相對路徑./assets/markdown-launch/image-01.png在本地一切正常但文章發(fā)布到平臺后圖片地址沒有對應(yīng)的域名和目錄自然全部裂開。所以正確路線是三步本地圖片統(tǒng)一放 assets 目錄發(fā)布前上傳到圖床換取 HTTPS 鏈接如果圖片量大建議再掛一層 CDN 做加速和縮放。圖床選型上我試過 PicGo 配合七牛云、阿里云 OSS、又拍云也用過一些免費圖床。最后固定下來的是 PicGo 自有對象存儲核心考慮是穩(wěn)定性——免費圖床省了錢但域名隨時可能被墻、被防盜鏈哪天圖片全成 xxx 就很難受。PicGo 的優(yōu)勢是可以自定義上傳路徑和 URL 規(guī)則批量上傳后自動生成 Markdown 格式的鏈接直接復(fù)制替換原稿里的相對路徑就行。批量替換時我寫過一個簡單的 Python 腳本本質(zhì)是讀 md 文件、正則匹配、替換成幾十篇文章批量處理也就幾秒鐘。還有個容易被忽視的點圖片文件名中的中文和空格在任何 CDN 上大概率會產(chǎn)生編碼問題。建議上傳前統(tǒng)一改成小寫英文 數(shù)字短橫線風格例如multi-platform-publish-01.png。這個習慣能避免一批莫名其妙的 404。3.3 表格兼容性復(fù)制過去為什么列全錯亂表格是另一個重災(zāi)區(qū)。本地 Typora 里畫好的表格看著很整潔復(fù)制到知乎專欄可能整個表格結(jié)構(gòu)就散架了粘貼到公眾號后臺要么邊框全丟要么變成一串 HTML 代碼。原因是很多平臺富文本編輯器對 Markdown 表格的“管道符 橫線”語法渲染有限復(fù)制時只會復(fù)制純文本無法還原表格結(jié)構(gòu)。我在多次實測后定下這樣幾條規(guī)則發(fā)布到掘金、CSDN、博客園這類技術(shù)平臺直接用原生 Markdown 表格它們普遍支持良好發(fā)布到知乎、公眾號這類平臺改用 HTML 形式的table表格粘貼后能保留結(jié)構(gòu)表格列數(shù)超過 6 列或者內(nèi)容過多時直接導(dǎo)出成圖片可讀性遠勝任何文本表格另外表格和 Excel 又是另一個場景。有時候我在 Typora 里排好的表格同事想要 Excel 版本Typora 本身提供了“復(fù)制為表格內(nèi)容”直接粘貼到 Excel 的功能但這不是博客發(fā)布場景別把它和平臺粘貼混淆了。我做了一個小工具腳本可以把任何一個 Markdown 表格解析成 HTML 表格字符串輸出發(fā)布前拷貝過去效果很穩(wěn)定。3.4 代碼塊高亮和縮進的隱藏規(guī)則代碼塊看起來簡單實際發(fā)布時細節(jié)很多。首先是語言標記千萬別偷懶不寫python和裸的在所有平臺上的高亮效果完全不同。我習慣在每段代碼上標語言并且只在少數(shù)支持附加屬性的平臺如博客園使用python {titlexxx.py lineNumberstrue}這類寫法換到其他平臺會先去掉附加屬性防止渲染錯誤。更隱蔽的問題是公眾號。公眾號編輯器對 Markdown 代碼塊里的空格和縮進支持極差直接粘貼時前導(dǎo)空格可能被吃掉代碼整體左縮進或歪掉。我通常會用專門工具做一次“Markdown 轉(zhuǎn)公眾號 HTML”把代碼塊包進precode標簽再粘貼到公眾號后臺。粘貼完后一定要點開預(yù)覽檢查縮進和轉(zhuǎn)義字符這一步省不了。3.5 數(shù)學公式與 GitHub Callout 等進階語法進階語法這里我說一下數(shù)學公式和 Callout 的適配。數(shù)學公式目前主流寫法是$行內(nèi)公式$和$$塊級公式$$。Typora 默認開啟了數(shù)學擴展后本地體驗很好但發(fā)布時可惜的是掘金、CSDN 和博客園支持度尚可知乎是半殘狀態(tài)公眾號則完全不能渲染。我的妥協(xié)方案是涉及復(fù)雜公式的場景直接導(dǎo)出一個公式截圖或者 SVG 文件作為圖片插入正文。這在視覺上傳真度接近原版又規(guī)避了各平臺渲染引擎差異。Callout 是 GitHub 風格的強調(diào)塊寫法是 [!NOTE]、 [!WARNING]。這種語法在 GitHub 上很棒但能在博客平臺渲染出來的少之又少。我自己的策略是如果目標平臺不支持 Callout就在源稿里把這類塊改寫為普通引用塊 加粗標題效果不差還更通用。高級語法和通用語法之間要做取舍優(yōu)先保底線兼容。3.6 不同渠道的特定格式公眾號、釘釘、微博除了傳統(tǒng)博客平臺很多人還會把 Markdown 內(nèi)容同步到公眾號甚至用釘釘機器人發(fā)一些消息通知。公眾號那邊我見過有人硬搬 Markdown 文本進去出來的效果基本不能看。正確做法是先用 md2wechat 這類工具把文章轉(zhuǎn)成帶內(nèi)聯(lián)樣式的 HTML再粘貼到公眾號編輯器。轉(zhuǎn)換后的標題、引用、代碼塊、列表樣式都不太需要二次調(diào)整我只用再手動處理一下分割線和圖片注釋。釘釘?shù)摹邦A(yù)警”和“消息卡片”是另一個常見場景。釘釘?shù)?Markdown 消息格式和博客 Markdown 不是一回事它支持## 標題、- 列表、**加粗**這些基礎(chǔ)語法但不支持圖片和復(fù)雜表格代碼塊也是受限的。我之前踩過一次坑把一份完整技術(shù)文章往釘釘機器人推送結(jié)果變成了純文本堆疊。后來我調(diào)整了做法釘釘消息只放要點摘要正文附鏈接格式清爽多了。微博就更特殊了原生發(fā)布器不支持 Markdown一般有兩種處理短期通告類內(nèi)容直接轉(zhuǎn)成長圖發(fā)布如果是正經(jīng)技術(shù)文章建議用網(wǎng)頁版一些支持 Markdown 轉(zhuǎn)長圖的小工具生成一張高清長圖。圖片可以完整保留代碼高亮和代碼塊樣式體驗可以接受但要注意長圖寬高比別太夸張。4. 多平臺發(fā)布實操流程從定稿到分發(fā)4.1 主流平臺 Markdown 支持度對比先把主流平臺的 Markdown 支持情況列成一張表這是我實測下來比較公允的結(jié)論僅供參考平臺規(guī)則更新后可能要微調(diào)平臺原生 Markdown代碼高亮數(shù)學公式表格兼容備注掘金好好支持好粘貼體驗較好CSDN較好好支持一般標題、圖片需檢查博客園好好支持較好可自定義樣式知乎部分支持一般半殘差建議 HTML 表格簡書好較好不支持一般代碼塊正常公眾號不支持不支持不支持差必須用轉(zhuǎn)換工具思否好好支持好相對省心這個表的核心價值是輔助判斷發(fā)布到哪個平臺該走哪條適配規(guī)則。我一般把平臺分成兩類一類是“原生容器”比如掘金、博客園、思否規(guī)則簡單一類是“富文本容器”比如公眾號、知乎必須經(jīng)過一層轉(zhuǎn)換。4.2 手動發(fā)布的黃金步驟如果你還沒接自動化手動發(fā)布也可以很穩(wěn)。我現(xiàn)在每次發(fā)布都按下面這套順序走基本不會漏掉檢查項本地 Typora 打開源稿先跑一遍 markdownlint 修復(fù)格式問題用 PicGo 批量上傳文章內(nèi)所有圖片替換 md 中的圖片路徑針對目標平臺執(zhí)行對應(yīng)的適配規(guī)則表格轉(zhuǎn) HTML、公式轉(zhuǎn)圖、Callout 改寫將適配后的完整 Markdown 復(fù)制到平臺的 Markdown 編輯器發(fā)布前預(yù)覽重點看圖片、代碼高亮、表格、標題層級發(fā)布后打開線上文章頁面再快速掃一遍格式回到源稿把圖片路徑更新為圖床鏈接提交 Git 存檔第 7 步很多人不做我強烈建議養(yǎng)成習慣。否則源稿和線上版本不一致下次想改版重發(fā)會發(fā)現(xiàn)圖片全是相對路徑又得重新查一遍。4.3 各平臺的適配細節(jié)實錄針對幾個重點平臺我說幾個實測細節(jié)。掘金是當前支持 Markdown 比較省心的平臺直接把適配后的文本粘貼進去就行唯一要注意的是文章封面圖需要單獨上傳正文里的首圖容易因為路徑問題被折疊。博客園自由度最高它甚至允許自定義 CSS我一般會把代碼塊的字體、背景微調(diào)成自己習慣的樣式但要注意主題之間的兼容。知乎那邊表格和圖片是兩大軟肋。表格我全部轉(zhuǎn)成tableHTML 后粘貼實測結(jié)構(gòu)穩(wěn)定圖片用圖床鏈接且要勾選“保存到知乎圖集”否則部分移動端場景會出現(xiàn)防盜鏈提示。公眾號這里再強調(diào)一次任何所謂“公眾號 Markdown 編輯器”本質(zhì)都是把 Markdown 轉(zhuǎn)成內(nèi)聯(lián)樣式 HTML你只管排版不用理解它內(nèi)部的那些按鈕。發(fā)布后最好用手機預(yù)覽一下因為很多樣式在 PC 后臺看是正常的手機上段間距、字體大小才會露餡。CSDN 情況稍微特殊它對 Markdown 支持其實不錯但平臺會默認給你插入一些推廣內(nèi)容和“目錄生成”占位發(fā)布前要把這些額外內(nèi)容檢查掉有時文章開頭會有非 Markdown 語法導(dǎo)致的標題錯位需要手動修正一級標題。4.4 半自動與自動化實踐腳本、工具鏈與 Coze 工作流如果你文章量大建議做半自動化。我目前的半自動流程是這樣的PicGo 負責圖片上傳和鏈接生成一個 Python 腳本負責批量替換 md 里的圖片路徑另一個腳本負責把文章按目標平臺拆成不同導(dǎo)出版本最后配合一個本地快捷鍵工具把適配后的文本一鍵復(fù)制到剪貼板。隨著現(xiàn)在大模型工作流工具變多用 Coze 這類平臺搭“Markdown 轉(zhuǎn) Word”或者“Markdown 格式化”工作流也成了不少人的選擇。我自己搭過一個簡單的工作流輸入 md 文本調(diào)用 API 返回 HTML再輸出到指定格式。這個思路適合做中轉(zhuǎn)和批處理但要注意格式損耗——每次自動化轉(zhuǎn)換都可能引入新的奇怪空格或字符跑完后一定人工抽查。拿它做常用格式的預(yù)處理可以指望它全自動完美發(fā)布以我目前測過的效果還不現(xiàn)實。5. 常見問題排查與避坑實錄5.1 表格粘貼后列錯位、邊框丟失出現(xiàn)這個問題的原因幾乎是固定的平臺富文本編輯器把 Markdown 表格當純文本粘貼或者只識別了一部分管道符。解決方法是粘貼前把 Markdown 表格改成 HTMLtable字符串再粘貼。在知乎和公眾號上我測試過 30 列以上的大表格用 HTML 標簽基本不會錯位。如果一定要用原生 Markdown 表格只建議發(fā)掘金這種原生支持好的平臺。5.2 圖片加載不出來大概率三種原因圖片還是相對路徑、圖床域名被防盜鏈、上傳后圖片被壓縮導(dǎo)致路徑變化。我個人排查順序是先看瀏覽器直接訪問圖床鏈接是否 200再看站點是否加了防盜鏈 Referer 限制最后檢查 md 里是不是有中文路徑未編碼。對了本地相對路徑改圖床鏈接時記得把./前綴去掉否則拼接 URL 時會多出一段相對路徑。5.3 代碼縮進被吃掉、高亮失效公眾號是最常見的縮進殺手。處理辦法前面提過用precode包裹代碼。高亮失效則多是因為代碼塊語言標識沒寫或者平臺對python linenums1這類擴展語法不識別。我的辦法是統(tǒng)一使用純語言標記不給自己加戲。高亮行號如果平臺原生不支持就不要強求至少代碼本身要整齊。5.4 數(shù)學公式變成亂碼或整段消失公式亂碼十有八九是行內(nèi)公式$...$被平臺當成了普通文本過濾或轉(zhuǎn)義。解決方案有三個改用塊級$$...$$發(fā)布后檢查還是不行就轉(zhuǎn)成圖片最不濟直接改為文字化描述。就我的經(jīng)驗技術(shù)博客如果沒有極端的公式需求能用“x 的平方”這類文字表達的就盡量用文字渲染問題直接繞開。5.5 排查速查表癥狀可能原因處理方案段落黏連缺少空行分段加空行行內(nèi)強制換行失效依賴了兩個空格換行改用列表或空行圖片全部裂開相對路徑/防盜鏈圖床 URL 檢查 Referer表格錯位平臺不兼容 Markdown 表格改用 HTML 表格代碼縮進丟失富文本壓縮空格用pre包裹后粘貼代碼高亮失效未寫語言或擴展語法不被識別只寫python公式亂碼平臺不支持$語法使用塊級公式或轉(zhuǎn)圖釘釘消息樣式混亂使用了博客語法只用基礎(chǔ)語法 摘要6. 實測工作流我的一次真實發(fā)布過程6.1 從寫稿到發(fā)布的標準動作我舉一個實際例子。假設(shè)今天要寫一篇《用 Python 寫爬蟲的 5 個提醒》平臺目標是掘金、公眾號、知乎。我的流程是這樣的在 Typora 寫稿assets 目錄建python-crawler-tips/子目錄插圖全部拖進去。寫完跑一遍 markdownlint確認標題層級只有 H1/H2/H3無 H4 以上跳躍。打開 Typora 偏好設(shè)置里的“復(fù)制 Markdown 源碼”功能先把整篇復(fù)制到剪貼板然后以 Markdown 源稿為基線依次做三份導(dǎo)出掘金版直接粘貼源稿圖片替換成圖床鏈接發(fā)布后花兩分鐘過一遍標題和代碼。公眾號版跑一遍 md2wechat 轉(zhuǎn)換把輸出粘貼到公眾號編輯器再用手機預(yù)覽確認樣式。知乎版在源稿基礎(chǔ)上把表格全部替換成 HTML 表格公式部分轉(zhuǎn)成圖片粘貼前又特意檢查了一遍代碼塊語言標記。整個過程加起來大概 40 分鐘其中真正花在“格式適配”上的時間不超過 10 分鐘剩下的時間都用在內(nèi)容打磨上。6.2 我最終留下的工具清單最后整理一份我現(xiàn)在每天用的工具清單供參考分類工具用途替代方案編輯器Typora 1.11.x寫作與本地預(yù)覽VS Code、Obsidian格式檢查markdownlint修正語法規(guī)范IDE 自帶校驗圖片上傳PicGo 對象存儲圖床鏈接生成iPic、路過圖床表格轉(zhuǎn)換自寫 Python 腳本Markdown 表格轉(zhuǎn) HTML在線轉(zhuǎn)換工具公眾號轉(zhuǎn)換md2wechatMarkdown 轉(zhuǎn)公眾號 HTMLMarkdown Nice版本管理Git GitHub源稿存檔與回溯堅果云、本地備份6.3 回頭看的一些個人選擇回頭看這七八年折騰下來的經(jīng)驗我最大的體會是不要迷信任何“一鍵發(fā)布全平臺”的工具。各平臺的編輯器和渲染規(guī)則是動態(tài)變化的今天好用的插件明天可能就失效了。相比之下一套基于 Markdown 源稿 明確適配規(guī)則 少量腳本的流程反而最穩(wěn)定因為它把不確定的部分拆開來了每塊都可以獨立測試和修正。如果你正準備從富文本切換到 Markdown 流程別貪心先只跑一個平臺試試跑通后再把其他平臺映射進來。這套東西的核心價值不是省那點復(fù)制粘貼的時間而是讓你對每次發(fā)布的格式有確定性預(yù)期——知道哪個環(huán)節(jié)可能出問題、出了問題去哪修。這是我無論如何都不想放棄它的原因。