工作日晚上十一點(diǎn)剛把一篇寫好的技術(shù)文章從Markdown編輯器復(fù)制到公眾號后臺標(biāo)題、正文都還正常一到代碼塊部分就徹底崩了縮進(jìn)全丟、背景色沒了、高亮變成黑色純文本。盯著后臺編輯器那副“寧死不屈”的樣子我實(shí)在沒忍住把之前攢的幾套排版方案全翻出來比了一遍。最后讓我徹底解脫的就是這個(gè)叫md2wechat-skill的小工具。先交代一下它是什么。md2wechat-skill是一個(gè)本地運(yùn)行的Markdown轉(zhuǎn)公眾號HTML工具核心思路是把你寫好的markdown文件處理成一份“內(nèi)聯(lián)樣式全開”的HTML文檔。所謂內(nèi)聯(lián)樣式指的是所有樣式直接寫在標(biāo)簽的style屬性里而不是依賴外部CSS文件或class類名。這樣處理過的HTML粘貼到微信公眾號后臺之后格式會最大程度地保留下來代碼塊、表格、引用、列表基本不用再手動修。這篇文章不是什么官方教程的復(fù)讀是我在實(shí)際安裝、配置、跑通、踩坑之后整理的一份實(shí)戰(zhàn)記錄。從環(huán)境準(zhǔn)備、依賴版本、配置文件詳解到完整轉(zhuǎn)換流程和高頻問題排查一次性說清楚。如果你也是用Markdown寫作、需要發(fā)公眾號的內(nèi)容創(chuàng)作者或者你想把“md轉(zhuǎn)公眾號”這一步塞進(jìn)自動化流程里這篇文章應(yīng)該能幫你省下不少周末時(shí)間。1. 先把思路理順md2wechat-skill 到底解決了什么問題1.1 公眾號排版與 Markdown 的天然沖突用過公眾號后臺的人都有體會它的編輯器是一個(gè)非?！胺忾]”的富文本環(huán)境。你在本地用Markdown寫得好好的標(biāo)題層級、列表縮進(jìn)、代碼塊格式一旦粘貼進(jìn)去經(jīng)常變得面目全非。根本原因在于公眾號后臺在粘貼時(shí)會過濾掉大部分class類名和外部樣式表只保留一部分內(nèi)聯(lián)style屬性。以代碼塊為例。Markdown渲染之后默認(rèn)生成的標(biāo)簽結(jié)構(gòu)大致是precode classlanguage-javascript代碼高亮依賴的是外部CSS里定義的.language-javascript相關(guān)規(guī)則。這類class在粘貼時(shí)被過濾之后代碼塊就變成了一坨沒有背景色、沒有縮進(jìn)、沒有高亮的純文本。而本地Markdown預(yù)覽時(shí)看著好好的是因?yàn)楸镜劁秩酒靼袰SS文件加載進(jìn)來了并不是公眾號后臺能識別。md2wechat-skill的思路很直接在轉(zhuǎn)換階段就把所有樣式從“class定義的樣式表”變成“元素上的style屬性”。比如代碼塊會直接生成pre stylebackground-color: #f6f8fa; padding: 16px; border-radius: 4px; font-family: monospace;這樣的標(biāo)簽。公眾號后臺雖然會過濾class但對style屬性的容忍度高出很多于是樣式就成了粘貼后的“幸存者”。打個(gè)比方class類名就像圖書館里的索引編號只有通過圖書館的系統(tǒng)才能查到對應(yīng)的書而style屬性就像直接貼在書上的內(nèi)容標(biāo)簽任何人拿到書都能看見。公眾號后臺不認(rèn)你那套“圖書館系統(tǒng)”但認(rèn)得“標(biāo)簽”。1.2 對比三種常見方案為什么選本地轉(zhuǎn)換在決定用一個(gè)專門工具之前我把市面上常見的路徑都試了一圈。手動排版、在線轉(zhuǎn)換工具、本地命令行工具各有各的取舍。方案優(yōu)點(diǎn)缺點(diǎn)手動排版最靈活想怎么調(diào)怎么調(diào)每篇文章半小時(shí)起步批量處理不現(xiàn)實(shí)在線轉(zhuǎn)換工具打開網(wǎng)頁就能用界面友好原文章內(nèi)容要上傳到第三方服務(wù)器模板和樣式自定義能力弱本地命令行工具樣式可配置、支持批量、可離線使用需要裝命令行環(huán)境初次配置有學(xué)習(xí)成本手動排版我堅(jiān)持了相當(dāng)長一段時(shí)間直到有一次一周連發(fā)三篇文章每篇都要在后臺反復(fù)調(diào)代碼塊樣式實(shí)在撐不住了。在線轉(zhuǎn)換工具倒是省事但我有幾篇沒發(fā)布的文章內(nèi)容不太想傳到第三方服務(wù)上而且它們給到的可配置項(xiàng)通常只有“主題A”“主題B”字體大小、行間距、引用塊樣式這些細(xì)節(jié)基本動不了。md2wechat-skill這類本地工具最大的優(yōu)勢是可配置性和可批量性。配置文件里改一行整體樣式就全變了輸入目錄里放幾十篇Markdown一條命令全部轉(zhuǎn)換成HTML。這種能力對維護(hù)一個(gè)歷史文章庫來說非常重要。1.3 工具的核心工作原理一鍵完成轉(zhuǎn)換與內(nèi)聯(lián)如果你已經(jīng)了解過一些Markdown渲染器可能會問這不就是“把Markdown渲染成HTML”嗎確實(shí)核心步驟的第一層就是渲染但最關(guān)鍵的是第二層——樣式內(nèi)聯(lián)化。整個(gè)處理流程大致分四步。第一步讀取Markdown原始文件解析出標(biāo)題、段落、列表、引用、代碼塊、表格等結(jié)構(gòu)化內(nèi)容。第二步用內(nèi)置的渲染引擎把Markdown語法轉(zhuǎn)換成標(biāo)準(zhǔn)的HTML標(biāo)簽結(jié)構(gòu)。第三步也是這個(gè)工具的重點(diǎn)把預(yù)設(shè)的主題樣式表“映射”到對應(yīng)的HTML元素上轉(zhuǎn)換成style屬性。這一步會處理標(biāo)題的字體大小、段落的行高、表格的邊框、代碼塊的背景色和語法高亮顏色等等。第四步輸出一個(gè)完整的HTML文件附加一些必要的meta信息。因?yàn)樗袠邮蕉純?nèi)聯(lián)了所以生成的HTML文件單獨(dú)用瀏覽器打開時(shí)和你最終粘貼到公眾號后臺看到的視覺效果幾乎是完全一致的。這在調(diào)試樣式的時(shí)候特別方便——你不需要每次都跑到公眾號后臺試錯(cuò)本地瀏覽器里刷新一下就知道效果。2. 安裝前準(zhǔn)備與正式安裝流程2.1 運(yùn)行環(huán)境和依賴版本選擇安裝之前先確認(rèn)電腦上有沒有JavaScript運(yùn)行時(shí)環(huán)境。這個(gè)工具是用JavaScript寫的運(yùn)行需要Node.js環(huán)境而且版本不能太老。我實(shí)測下來Node.js 16及以上的版本比較穩(wěn)定14也能跑但如果你遇到莫名其妙的語法報(bào)錯(cuò)大概率是版本太舊導(dǎo)致的。打開終端先敲兩個(gè)命令檢查一下node -v npm -v如果能看到版本號比如v16.20.0和9.6.0說明環(huán)境已經(jīng)就緒。如果提示command not found那就需要先裝Node.js。這里建議優(yōu)先考慮用“nvm”這類版本管理工具安裝而不是直接去下載官網(wǎng)的安裝包。原因很現(xiàn)實(shí)nvm可以隨時(shí)切換Node版本后面如果遇到某個(gè)依賴包死活裝不上切個(gè)版本往往就解決了省去重裝系統(tǒng)的麻煩。npm是Node.js自帶的包管理器后面所有依賴的下載安裝都由它負(fù)責(zé)。安裝依賴時(shí)需要聯(lián)網(wǎng)但只在安裝這一步需要裝完之后日常轉(zhuǎn)換完全是本地運(yùn)行的。2.2 安裝主程序與驗(yàn)證環(huán)境確認(rèn)沒問題之后安裝過程本身很簡單npm install -g md2wechat-skill-g參數(shù)表示全局安裝裝完之后系統(tǒng)里就會多一個(gè)md2wechat命令。等安裝進(jìn)度條跑完驗(yàn)證一下md2wechat --version如果正常輸出了版本號說明安裝成功。如果你看到的是command not found那就需要檢查npm全局安裝目錄是否在系統(tǒng)PATH里。先用npm config get prefix查看全局目錄比如返回的是/usr/local那么對應(yīng)的bin目錄就是/usr/local/bin。把它加到shell配置文件比如.zshrc或.bash_profile的PATH中重新加載配置文件之后就好了。這里有一個(gè)細(xì)節(jié)值得注意千萬不要因?yàn)闄?quán)限問題一上來就加sudo。如果npm報(bào)出EACCES這類權(quán)限錯(cuò)誤說明當(dāng)前用戶對全局目錄沒有寫權(quán)限。用sudo npm install -g雖然能裝上但后面運(yùn)行時(shí)會留下各種莫名其妙的文件歸屬問題。更干凈的解法是用nvm重新安裝Node.js讓所有全局包都落到用戶目錄下一勞永逸。如果暫時(shí)不想全局安裝也可以只在某個(gè)項(xiàng)目里臨時(shí)用一下npx md2wechat-skill --versionnpx會自動調(diào)取并緩存工具到本地目錄適合偶爾用一次的場景。2.3 初始化目錄和默認(rèn)配置文件安裝驗(yàn)證通過后建議專門建一個(gè)存放文章素材的工作目錄而不是隨手扔在某個(gè)臨時(shí)文件夾里。我的目錄結(jié)構(gòu)是這樣的mkdir -p my-posts/input my-posts/output cd my-posts然后執(zhí)行初始化命令md2wechat init執(zhí)行之后目錄下會多出兩個(gè)文件md2wechat.config.json和template.html。前者是工具的全局配置文件后者是自定義頁面模板后面會詳細(xì)說明。第一次使用我的建議是不要急著改配置直接用默認(rèn)配置跑通一次完整流程確認(rèn)工具本身可用、你能看到預(yù)期的HTML輸出再去動那些樣式參數(shù)。先把基礎(chǔ)設(shè)施建好再談裝修。直接上手就改一堆配置容易把問題混合在一起到時(shí)候分不清是配置寫錯(cuò)了還是工具沒裝好。3. 配置解析把默認(rèn)樣式改成你自己的風(fēng)格3.1 配置文件逐項(xiàng)拆解配置文件是整個(gè)工具里最值得花時(shí)間研究的文件所有排版偏好都集中在這里。先看一個(gè)完整的示例{ title: 我的文章, author: 某開發(fā)者, outputDir: output, toc: true, tocDepth: 3, fontSize: 16px, lineHeight: 1.75, contentWidth: 680, textAlign: left, imageAlign: center, imageRadius: 4px, codeTheme: light, quoteStyle: border-left, footer: p版權(quán)聲明本文為原創(chuàng)內(nèi)容轉(zhuǎn)載請注明出處。/p }逐個(gè)說。title和author會生成文章頂部的基本信息區(qū)。如果你的Markdown第一行已經(jīng)有# 標(biāo)題也可以把title設(shè)為空字符串由工具自動識別Markdown里的主標(biāo)題。outputDir是HTML輸出目錄名可以用絕對路徑也可以用相對路徑。toc控制是否生成目錄tocDepth控制目錄包含到第幾級標(biāo)題。長文章建議開啟目錄但短篇文章我反而建議關(guān)掉——目錄區(qū)域在公眾號后臺有時(shí)候會出現(xiàn)行距異常最后還是要手動調(diào)整性價(jià)比不高。fontSize和lineHeight是正文的基礎(chǔ)樣式參數(shù)。contentWidth是正文區(qū)的模擬寬度影響圖片和表格的顯示寬度上限。imageAlign控制圖片對齊方式imageRadius控制圖片圓角大小。codeTheme是代碼高亮主題名quoteStyle是引用塊的樣式方案。最后的footer用于設(shè)置頁腳版權(quán)信息。每次修改配置文件之后需要重新執(zhí)行轉(zhuǎn)換命令讓配置重新生效。3.2 核心排版參數(shù)的最佳取值關(guān)于字號和行距我自己測試下來16px字號、1.75倍行距是比較穩(wěn)妥的組合。手機(jī)屏幕寬度通常按375px計(jì)算去掉內(nèi)邊距后正文區(qū)大概剩余348px16px的中文字符一行大約能排22~24個(gè)字閱讀起來眼睛不累。行距太緊湊長段落會顯得“糊成一團(tuán)”行距太松散整個(gè)文章又會顯得稀稀拉拉。1.75倍在線下打印和手機(jī)閱讀之間取了個(gè)平衡。引用塊樣式我強(qiáng)烈建議用border-left方案也就是左側(cè)加一條豎線而不是整個(gè)背景變色。原因很實(shí)際公眾號后臺在手機(jī)端夜間模式下部分背景色會被系統(tǒng)默認(rèn)樣式覆蓋導(dǎo)致引用塊變成深底深字或者淺底淺字可讀性很差。左側(cè)邊框方案在不同模式下表現(xiàn)都穩(wěn)定。代碼塊主題我推薦淺色底、深色字的方案。之前在配置里把代碼塊設(shè)成深色背景白天預(yù)覽沒問題但到了夜間模式深色背景和系統(tǒng)的反色邏輯疊加整個(gè)代碼塊就“黑成一坨”。換回淺色主題后無論是白天還是夜間都能保持清晰的對比度。表格方面工具會默認(rèn)加上table-layout: fixed和width: 100%避免列數(shù)多的表格被后臺編輯器壓縮得無法辨認(rèn)。如果你的表格超過五六列建議拆分成多張小表比任何樣式設(shè)置都有效。3.3 自定義模板加入品牌頁腳和版權(quán)信息除了配置文件里簡單的footer文本更復(fù)雜的頁面結(jié)構(gòu)需要修改template.html。模板文件就是一個(gè)完整的HTML文檔骨架里面預(yù)留了一個(gè)內(nèi)容插入標(biāo)記。執(zhí)行轉(zhuǎn)換時(shí)工具會把轉(zhuǎn)換好的正文嵌入到模板的指定位置。比如想每篇文章底部都放一段品牌介紹、一個(gè)二維碼內(nèi)容區(qū)、以及版權(quán)聲明就可以在模板正文末尾添加對應(yīng)的HTML片段。這里要特別強(qiáng)調(diào)模板中不能依賴外部CSS文件也不能使用外鏈字體因?yàn)檎迟N到公眾號后臺時(shí)所有外部資源都不會被加載。模板里涉及樣式的部分最終必須也經(jīng)過工具的內(nèi)聯(lián)化處理生成style屬性才能保證粘貼后不丟樣式。模板還有一個(gè)價(jià)值就是團(tuán)隊(duì)協(xié)作。如果幾個(gè)人同時(shí)維護(hù)一個(gè)公眾號只要共享同一份模板和配置文件大家產(chǎn)出的排版風(fēng)格就能保持一致不需要每個(gè)人各自在后臺調(diào)一遍樣式。4. 完整實(shí)戰(zhàn)從Markdown到公眾號后臺4.1 準(zhǔn)備一篇功能齊全的測試文章為了把轉(zhuǎn)換效果完整看一遍我在input目錄下新建了一篇測試文章里面覆蓋了標(biāo)題、段落、列表、引用、代碼塊、表格和圖片這些常見元素。內(nèi)容大致是這樣# 模擬項(xiàng)目X的開發(fā)記錄 完成這個(gè)項(xiàng)目之后我最大的感受是工具鏈的完善程度直接影響最終產(chǎn)出的穩(wěn)定性。 ## 項(xiàng)目背景 模擬項(xiàng)目X是一個(gè)用于驗(yàn)證自動化發(fā)布流程的示例項(xiàng)目。 - 使用 Markdown 編寫文檔 - 通過命令行轉(zhuǎn)換為公眾號 HTML - 手動粘貼到后臺發(fā)布 | 模塊 | 狀態(tài) | 備注 | | ---- | ---- | ---- | | 登錄 | 已完成 | 使用內(nèi)部賬號體系 | | 數(shù)據(jù)同步 | 進(jìn)行中 | 依賴后臺定時(shí)任務(wù) | | 郵件通知 | 未開始 | 下個(gè)迭代處理 |  javascript function hello() { return hello world; }注意雖然不是必須但我建議先準(zhǔn)備一篇包含全部元素的小文章來做測試不要直接用一篇上萬字的長文。這樣跑通流程之后就能在最短時(shí)間內(nèi)檢查每個(gè)元素在最終HTML里的表現(xiàn)。 ### 4.2 執(zhí)行轉(zhuǎn)換與預(yù)覽效果 運(yùn)行轉(zhuǎn)換命令 bash md2wechat -i input/test.md -o output/test.html執(zhí)行后終端會有類似下面的提示[info] 已讀取 input/test.md [info] 正在生成 HTML... [info] 樣式內(nèi)聯(lián)完成 [info] 已輸出 output/test.html然后直接用瀏覽器打開output/test.html。正常情況下能看到一級標(biāo)題清晰醒目引用塊左側(cè)有一條豎線代碼塊有淺色背景和語法高亮表格表頭有底色、邊框完整圖片居中并帶一點(diǎn)圓角。最關(guān)鍵的是打開瀏覽器開發(fā)者工具隨便點(diǎn)一個(gè)元素查看樣式所有樣式都應(yīng)該直接寫在style屬性里而不是出現(xiàn)在某個(gè)CSS文件里。這一點(diǎn)是整個(gè)方案成立的基礎(chǔ)也是粘貼到公眾號后臺不失真的前提。4.3 粘貼到公眾號后臺的關(guān)鍵流程粘貼流程我優(yōu)化過幾次總結(jié)出靠譜的步驟如下。先在瀏覽器里打開生成的HTML文件使用全選快捷鍵CtrlAmacOS上是CmdA再使用復(fù)制快捷鍵CtrlCmacOS上是CmdC。然后打開公眾號后臺新建圖文消息直接在正文編輯區(qū)使用粘貼快捷鍵CtrlV。粘貼完成之后依次檢查三個(gè)位置。第一標(biāo)題、作者信息是不是正確顯示第二代碼塊是不是保留了背景色和縮進(jìn)第三表格邊框是否完整。圖片是一個(gè)需要特別注意的點(diǎn)。如果Markdown里的圖片是本地相對路徑比如文章里寫的./assets/demo.png轉(zhuǎn)換出來的HTML里圖片地址也還是相對路徑而公眾號后臺是無法訪問你本機(jī)文件的。解決方案涉及一個(gè)重要的選擇如果圖片已經(jīng)上傳到圖床或素材庫就把Markdown里圖片路徑改成網(wǎng)絡(luò)URL再執(zhí)行轉(zhuǎn)換如果圖片是本地文件且體積不大也可以把工具提供的內(nèi)聯(lián)圖片選項(xiàng)打開會自動把圖片轉(zhuǎn)為base64內(nèi)嵌到HTML里。注意base64內(nèi)嵌方式會讓HTML體積膨脹十幾張圖加起來幾百KB是常有的事但勝在省事適合一次性內(nèi)容。5. 問題排查與經(jīng)驗(yàn)技巧5.1 安裝階段高頻踩坑安裝階段遇到最多的就是權(quán)限報(bào)錯(cuò)、命令找不到和版本過舊這三類問題。權(quán)限報(bào)錯(cuò)的典型表現(xiàn)是npm在安裝過程中輸出EACCES: permission denied。我看到不少人的第一反應(yīng)是加sudo但我個(gè)人不建議這樣做因?yàn)樗皇前褭?quán)限問題繞過去了后續(xù)可能會在全局目錄留下一些歸屬混亂的文件。更好的辦法是換用nvm來管理Node.js把全局包的安裝路徑放在用戶目錄內(nèi)徹底避開權(quán)限問題。命令找不到的典型情況是安裝成功了但執(zhí)行md2wechat時(shí)提示command not found。用npm config get prefix查看全局bin目錄然后確認(rèn)該目錄是否在PATH環(huán)境變量里。這個(gè)排查起來不復(fù)雜但容易出現(xiàn)尤其是剛換了電腦、shell配置文件還沒完整配置的時(shí)候。版本過舊的問題通常表現(xiàn)為轉(zhuǎn)換時(shí)出現(xiàn)類似Unexpected token ?的語法報(bào)錯(cuò)。這基本可以斷定是Node.js版本太老工具代碼里用到了新語法但當(dāng)前運(yùn)行環(huán)境不支持。升級Node.js之后重啟終端問題就能解決。5.2 轉(zhuǎn)換結(jié)果不符合預(yù)期怎么辦如果發(fā)現(xiàn)代碼塊沒有高亮先檢查配置文件里的codeTheme主題名是否寫對了。有些內(nèi)置主題的名字和你記憶里的不完全一致寫錯(cuò)時(shí)工具不會報(bào)錯(cuò)而是默默采用默認(rèn)主題所以看起來像是“功能壞了”?？梢詧?zhí)行md2wechat --list-themes查看可用主題列表然后再改配置。圖片顯示不出來九成是本地相對路徑問題。我自己最開始也在這個(gè)地方卡了一會兒以為轉(zhuǎn)換后的HTML已經(jīng)“自動處理圖片了”其實(shí)工具主要負(fù)責(zé)排版不負(fù)責(zé)圖片托管。如果不是使用base64內(nèi)聯(lián)Markdown里的圖片地址就必須是可被公網(wǎng)訪問的URL否則粘貼到后臺自然加載不出來。表格被壓扁或錯(cuò)位先看是不是列數(shù)太多了。工具對表格的樣式控制已經(jīng)比較全面但列數(shù)超過六列時(shí)再好的內(nèi)聯(lián)樣式也救不了窄屏上的閱讀體驗(yàn)。拆表是比調(diào)樣式更有效的辦法。5.3 批量轉(zhuǎn)換歷史文章和自動化等單篇流程完全跑通之后就可以把眼光放到批量處理上了。假設(shè)input目錄下有很多篇Markdown文章用一段簡單的shell腳本就能完成批量轉(zhuǎn)換#!/bin/bash mkdir -p output for f in input/*.md; do name$(basename $f .md) md2wechat -i $f -o output/${name}.html done執(zhí)行完腳本打開output目錄每一篇文章的HTML都生成好了排版風(fēng)格完全一致。這個(gè)批量能力是手動排版完全無法比擬的特別適合遷移歷史文章庫。再進(jìn)一步如果你有持續(xù)集成環(huán)境還可以把這個(gè)轉(zhuǎn)換命令接入項(xiàng)目流程。比如在代碼倉庫中創(chuàng)建一條自動化任務(wù)每當(dāng)用戶新增或修改了input目錄下的Markdown文件就自動執(zhí)行一次轉(zhuǎn)換生成HTML文件作為構(gòu)建產(chǎn)物。這就實(shí)現(xiàn)了從“寫文章”到“獲得排版好的HTML”的全自動銜接。批量之前有個(gè)前提一定先在單篇文章上把樣式調(diào)好再批量執(zhí)行。如果樣式?jīng)]調(diào)好就一次性跑幾十篇回頭改完配置又得全部重新跑一遍白白浪費(fèi)時(shí)間。我個(gè)人在實(shí)際操作中最舒服的狀態(tài)是本地用編輯器寫完Markdown推到倉庫后自動化任務(wù)自動生成HTML我只需要在瀏覽器里預(yù)覽一遍確認(rèn)無誤后復(fù)制粘貼到公眾號后臺。整個(gè)過程里需要手動干預(yù)的環(huán)節(jié)被壓到最少省出來的時(shí)間可以用來打磨內(nèi)容本身。關(guān)于你說到的把配置文件納入版本管理這一點(diǎn)我非常贊同。配置文件、模板文件、Markdown源文件建議放在同一個(gè)倉庫里換電腦或者換搭檔時(shí)一套環(huán)境直接同步過來風(fēng)格不會跑偏。后續(xù)如果你想繼續(xù)折騰還可以研究一下圖片壓縮、目錄自動生成、更多代碼高亮主題接入這些擴(kuò)展方向工具本身的設(shè)計(jì)余量還是比較充足的。