★ FEATURED ARTICLE 工作日晚上十一点刚把一篇写好的技术文章从Markdown编辑器复制到公众号后台标题、正文都还正常一到代码块部分就彻底崩了缩进全丢、背景色没了、高亮变成黑色纯文本。盯着后台编辑器那副“宁死不屈”的样子我实在没忍住把之前攒的几套排版方案全翻出来比了一遍。最后让我彻底解脱的就是这个叫md2wechat-skill的小工具。先交代一下它是什么。md2wechat-skill是一个本地运行的Markdown转公众号HTML工具核心思路是把你写好的markdown文件处理成一份“内联样式全开”的HTML文档。所谓内联样式指的是所有样式直接写在标签的style属性里而不是依赖外部CSS文件或class类名。这样处理过的HTML粘贴到微信公众号后台之后格式会最大程度地保留下来代码块、表格、引用、列表基本不用再手动修。这篇文章不是什么官方教程的复读是我在实际安装、配置、跑通、踩坑之后整理的一份实战记录。从环境准备、依赖版本、配置文件详解到完整转换流程和高频问题排查一次性说清楚。如果你也是用Markdown写作、需要发公众号的内容创作者或者你想把“md转公众号”这一步塞进自动化流程里这篇文章应该能帮你省下不少周末时间。1. 先把思路理顺md2wechat-skill 到底解决了什么问题1.1 公众号排版与 Markdown 的天然冲突用过公众号后台的人都有体会它的编辑器是一个非常“封闭”的富文本环境。你在本地用Markdown写得好好的标题层级、列表缩进、代码块格式一旦粘贴进去经常变得面目全非。根本原因在于公众号后台在粘贴时会过滤掉大部分class类名和外部样式表只保留一部分内联style属性。以代码块为例。Markdown渲染之后默认生成的标签结构大致是precode classlanguage-javascript代码高亮依赖的是外部CSS里定义的.language-javascript相关规则。这类class在粘贴时被过滤之后代码块就变成了一坨没有背景色、没有缩进、没有高亮的纯文本。而本地Markdown预览时看着好好的是因为本地渲染器把CSS文件加载进来了并不是公众号后台能识别。md2wechat-skill的思路很直接在转换阶段就把所有样式从“class定义的样式表”变成“元素上的style属性”。比如代码块会直接生成pre stylebackground-color: #f6f8fa; padding: 16px; border-radius: 4px; font-family: monospace;这样的标签。公众号后台虽然会过滤class但对style属性的容忍度高出很多于是样式就成了粘贴后的“幸存者”。打个比方class类名就像图书馆里的索引编号只有通过图书馆的系统才能查到对应的书而style属性就像直接贴在书上的内容标签任何人拿到书都能看见。公众号后台不认你那套“图书馆系统”但认得“标签”。1.2 对比三种常见方案为什么选本地转换在决定用一个专门工具之前我把市面上常见的路径都试了一圈。手动排版、在线转换工具、本地命令行工具各有各的取舍。方案优点缺点手动排版最灵活想怎么调怎么调每篇文章半小时起步批量处理不现实在线转换工具打开网页就能用界面友好原文章内容要上传到第三方服务器模板和样式自定义能力弱本地命令行工具样式可配置、支持批量、可离线使用需要装命令行环境初次配置有学习成本手动排版我坚持了相当长一段时间直到有一次一周连发三篇文章每篇都要在后台反复调代码块样式实在撑不住了。在线转换工具倒是省事但我有几篇没发布的文章内容不太想传到第三方服务上而且它们给到的可配置项通常只有“主题A”“主题B”字体大小、行间距、引用块样式这些细节基本动不了。md2wechat-skill这类本地工具最大的优势是可配置性和可批量性。配置文件里改一行整体样式就全变了输入目录里放几十篇Markdown一条命令全部转换成HTML。这种能力对维护一个历史文章库来说非常重要。1.3 工具的核心工作原理一键完成转换与内联如果你已经了解过一些Markdown渲染器可能会问这不就是“把Markdown渲染成HTML”吗确实核心步骤的第一层就是渲染但最关键的是第二层——样式内联化。整个处理流程大致分四步。第一步读取Markdown原始文件解析出标题、段落、列表、引用、代码块、表格等结构化内容。第二步用内置的渲染引擎把Markdown语法转换成标准的HTML标签结构。第三步也是这个工具的重点把预设的主题样式表“映射”到对应的HTML元素上转换成style属性。这一步会处理标题的字体大小、段落的行高、表格的边框、代码块的背景色和语法高亮颜色等等。第四步输出一个完整的HTML文件附加一些必要的meta信息。因为所有样式都内联了所以生成的HTML文件单独用浏览器打开时和你最终粘贴到公众号后台看到的视觉效果几乎是完全一致的。这在调试样式的时候特别方便——你不需要每次都跑到公众号后台试错本地浏览器里刷新一下就知道效果。2. 安装前准备与正式安装流程2.1 运行环境和依赖版本选择安装之前先确认电脑上有没有JavaScript运行时环境。这个工具是用JavaScript写的运行需要Node.js环境而且版本不能太老。我实测下来Node.js 16及以上的版本比较稳定14也能跑但如果你遇到莫名其妙的语法报错大概率是版本太旧导致的。打开终端先敲两个命令检查一下node -v npm -v如果能看到版本号比如v16.20.0和9.6.0说明环境已经就绪。如果提示command not found那就需要先装Node.js。这里建议优先考虑用“nvm”这类版本管理工具安装而不是直接去下载官网的安装包。原因很现实nvm可以随时切换Node版本后面如果遇到某个依赖包死活装不上切个版本往往就解决了省去重装系统的麻烦。npm是Node.js自带的包管理器后面所有依赖的下载安装都由它负责。安装依赖时需要联网但只在安装这一步需要装完之后日常转换完全是本地运行的。2.2 安装主程序与验证环境确认没问题之后安装过程本身很简单npm install -g md2wechat-skill-g参数表示全局安装装完之后系统里就会多一个md2wechat命令。等安装进度条跑完验证一下md2wechat --version如果正常输出了版本号说明安装成功。如果你看到的是command not found那就需要检查npm全局安装目录是否在系统PATH里。先用npm config get prefix查看全局目录比如返回的是/usr/local那么对应的bin目录就是/usr/local/bin。把它加到shell配置文件比如.zshrc或.bash_profile的PATH中重新加载配置文件之后就好了。这里有一个细节值得注意千万不要因为权限问题一上来就加sudo。如果npm报出EACCES这类权限错误说明当前用户对全局目录没有写权限。用sudo npm install -g虽然能装上但后面运行时会留下各种莫名其妙的文件归属问题。更干净的解法是用nvm重新安装Node.js让所有全局包都落到用户目录下一劳永逸。如果暂时不想全局安装也可以只在某个项目里临时用一下npx md2wechat-skill --versionnpx会自动调取并缓存工具到本地目录适合偶尔用一次的场景。2.3 初始化目录和默认配置文件安装验证通过后建议专门建一个存放文章素材的工作目录而不是随手扔在某个临时文件夹里。我的目录结构是这样的mkdir -p my-posts/input my-posts/output cd my-posts然后执行初始化命令md2wechat init执行之后目录下会多出两个文件md2wechat.config.json和template.html。前者是工具的全局配置文件后者是自定义页面模板后面会详细说明。第一次使用我的建议是不要急着改配置直接用默认配置跑通一次完整流程确认工具本身可用、你能看到预期的HTML输出再去动那些样式参数。先把基础设施建好再谈装修。直接上手就改一堆配置容易把问题混合在一起到时候分不清是配置写错了还是工具没装好。3. 配置解析把默认样式改成你自己的风格3.1 配置文件逐项拆解配置文件是整个工具里最值得花时间研究的文件所有排版偏好都集中在这里。先看一个完整的示例{ title: 我的文章, author: 某开发者, 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版权声明本文为原创内容转载请注明出处。/p }逐个说。title和author会生成文章顶部的基本信息区。如果你的Markdown第一行已经有# 标题也可以把title设为空字符串由工具自动识别Markdown里的主标题。outputDir是HTML输出目录名可以用绝对路径也可以用相对路径。toc控制是否生成目录tocDepth控制目录包含到第几级标题。长文章建议开启目录但短篇文章我反而建议关掉——目录区域在公众号后台有时候会出现行距异常最后还是要手动调整性价比不高。fontSize和lineHeight是正文的基础样式参数。contentWidth是正文区的模拟宽度影响图片和表格的显示宽度上限。imageAlign控制图片对齐方式imageRadius控制图片圆角大小。codeTheme是代码高亮主题名quoteStyle是引用块的样式方案。最后的footer用于设置页脚版权信息。每次修改配置文件之后需要重新执行转换命令让配置重新生效。3.2 核心排版参数的最佳取值关于字号和行距我自己测试下来16px字号、1.75倍行距是比较稳妥的组合。手机屏幕宽度通常按375px计算去掉内边距后正文区大概剩余348px16px的中文字符一行大约能排22~24个字阅读起来眼睛不累。行距太紧凑长段落会显得“糊成一团”行距太松散整个文章又会显得稀稀拉拉。1.75倍在线下打印和手机阅读之间取了个平衡。引用块样式我强烈建议用border-left方案也就是左侧加一条竖线而不是整个背景变色。原因很实际公众号后台在手机端夜间模式下部分背景色会被系统默认样式覆盖导致引用块变成深底深字或者浅底浅字可读性很差。左侧边框方案在不同模式下表现都稳定。代码块主题我推荐浅色底、深色字的方案。之前在配置里把代码块设成深色背景白天预览没问题但到了夜间模式深色背景和系统的反色逻辑叠加整个代码块就“黑成一坨”。换回浅色主题后无论是白天还是夜间都能保持清晰的对比度。表格方面工具会默认加上table-layout: fixed和width: 100%避免列数多的表格被后台编辑器压缩得无法辨认。如果你的表格超过五六列建议拆分成多张小表比任何样式设置都有效。3.3 自定义模板加入品牌页脚和版权信息除了配置文件里简单的footer文本更复杂的页面结构需要修改template.html。模板文件就是一个完整的HTML文档骨架里面预留了一个内容插入标记。执行转换时工具会把转换好的正文嵌入到模板的指定位置。比如想每篇文章底部都放一段品牌介绍、一个二维码内容区、以及版权声明就可以在模板正文末尾添加对应的HTML片段。这里要特别强调模板中不能依赖外部CSS文件也不能使用外链字体因为粘贴到公众号后台时所有外部资源都不会被加载。模板里涉及样式的部分最终必须也经过工具的内联化处理生成style属性才能保证粘贴后不丢样式。模板还有一个价值就是团队协作。如果几个人同时维护一个公众号只要共享同一份模板和配置文件大家产出的排版风格就能保持一致不需要每个人各自在后台调一遍样式。4. 完整实战从Markdown到公众号后台4.1 准备一篇功能齐全的测试文章为了把转换效果完整看一遍我在input目录下新建了一篇测试文章里面覆盖了标题、段落、列表、引用、代码块、表格和图片这些常见元素。内容大致是这样# 模拟项目X的开发记录 完成这个项目之后我最大的感受是工具链的完善程度直接影响最终产出的稳定性。 ## 项目背景 模拟项目X是一个用于验证自动化发布流程的示例项目。 - 使用 Markdown 编写文档 - 通过命令行转换为公众号 HTML - 手动粘贴到后台发布 | 模块 | 状态 | 备注 | | ---- | ---- | ---- | | 登录 | 已完成 | 使用内部账号体系 | | 数据同步 | 进行中 | 依赖后台定时任务 | | 邮件通知 | 未开始 | 下个迭代处理 |  javascript function hello() { return hello world; }注意虽然不是必须但我建议先准备一篇包含全部元素的小文章来做测试不要直接用一篇上万字的长文。这样跑通流程之后就能在最短时间内检查每个元素在最终HTML里的表现。 ### 4.2 执行转换与预览效果 运行转换命令 bash md2wechat -i input/test.md -o output/test.html执行后终端会有类似下面的提示[info] 已读取 input/test.md [info] 正在生成 HTML... [info] 样式内联完成 [info] 已输出 output/test.html然后直接用浏览器打开output/test.html。正常情况下能看到一级标题清晰醒目引用块左侧有一条竖线代码块有浅色背景和语法高亮表格表头有底色、边框完整图片居中并带一点圆角。最关键的是打开浏览器开发者工具随便点一个元素查看样式所有样式都应该直接写在style属性里而不是出现在某个CSS文件里。这一点是整个方案成立的基础也是粘贴到公众号后台不失真的前提。4.3 粘贴到公众号后台的关键流程粘贴流程我优化过几次总结出靠谱的步骤如下。先在浏览器里打开生成的HTML文件使用全选快捷键CtrlAmacOS上是CmdA再使用复制快捷键CtrlCmacOS上是CmdC。然后打开公众号后台新建图文消息直接在正文编辑区使用粘贴快捷键CtrlV。粘贴完成之后依次检查三个位置。第一标题、作者信息是不是正确显示第二代码块是不是保留了背景色和缩进第三表格边框是否完整。图片是一个需要特别注意的点。如果Markdown里的图片是本地相对路径比如文章里写的./assets/demo.png转换出来的HTML里图片地址也还是相对路径而公众号后台是无法访问你本机文件的。解决方案涉及一个重要的选择如果图片已经上传到图床或素材库就把Markdown里图片路径改成网络URL再执行转换如果图片是本地文件且体积不大也可以把工具提供的内联图片选项打开会自动把图片转为base64内嵌到HTML里。注意base64内嵌方式会让HTML体积膨胀十几张图加起来几百KB是常有的事但胜在省事适合一次性内容。5. 问题排查与经验技巧5.1 安装阶段高频踩坑安装阶段遇到最多的就是权限报错、命令找不到和版本过旧这三类问题。权限报错的典型表现是npm在安装过程中输出EACCES: permission denied。我看到不少人的第一反应是加sudo但我个人不建议这样做因为它只是把权限问题绕过去了后续可能会在全局目录留下一些归属混乱的文件。更好的办法是换用nvm来管理Node.js把全局包的安装路径放在用户目录内彻底避开权限问题。命令找不到的典型情况是安装成功了但执行md2wechat时提示command not found。用npm config get prefix查看全局bin目录然后确认该目录是否在PATH环境变量里。这个排查起来不复杂但容易出现尤其是刚换了电脑、shell配置文件还没完整配置的时候。版本过旧的问题通常表现为转换时出现类似Unexpected token ?的语法报错。这基本可以断定是Node.js版本太老工具代码里用到了新语法但当前运行环境不支持。升级Node.js之后重启终端问题就能解决。5.2 转换结果不符合预期怎么办如果发现代码块没有高亮先检查配置文件里的codeTheme主题名是否写对了。有些内置主题的名字和你记忆里的不完全一致写错时工具不会报错而是默默采用默认主题所以看起来像是“功能坏了”。可以执行md2wechat --list-themes查看可用主题列表然后再改配置。图片显示不出来九成是本地相对路径问题。我自己最开始也在这个地方卡了一会儿以为转换后的HTML已经“自动处理图片了”其实工具主要负责排版不负责图片托管。如果不是使用base64内联Markdown里的图片地址就必须是可被公网访问的URL否则粘贴到后台自然加载不出来。表格被压扁或错位先看是不是列数太多了。工具对表格的样式控制已经比较全面但列数超过六列时再好的内联样式也救不了窄屏上的阅读体验。拆表是比调样式更有效的办法。5.3 批量转换历史文章和自动化等单篇流程完全跑通之后就可以把眼光放到批量处理上了。假设input目录下有很多篇Markdown文章用一段简单的shell脚本就能完成批量转换#!/bin/bash mkdir -p output for f in input/*.md; do name$(basename $f .md) md2wechat -i $f -o output/${name}.html done执行完脚本打开output目录每一篇文章的HTML都生成好了排版风格完全一致。这个批量能力是手动排版完全无法比拟的特别适合迁移历史文章库。再进一步如果你有持续集成环境还可以把这个转换命令接入项目流程。比如在代码仓库中创建一条自动化任务每当用户新增或修改了input目录下的Markdown文件就自动执行一次转换生成HTML文件作为构建产物。这就实现了从“写文章”到“获得排版好的HTML”的全自动衔接。批量之前有个前提一定先在单篇文章上把样式调好再批量执行。如果样式没调好就一次性跑几十篇回头改完配置又得全部重新跑一遍白白浪费时间。我个人在实际操作中最舒服的状态是本地用编辑器写完Markdown推到仓库后自动化任务自动生成HTML我只需要在浏览器里预览一遍确认无误后复制粘贴到公众号后台。整个过程里需要手动干预的环节被压到最少省出来的时间可以用来打磨内容本身。关于你说到的把配置文件纳入版本管理这一点我非常赞同。配置文件、模板文件、Markdown源文件建议放在同一个仓库里换电脑或者换搭档时一套环境直接同步过来风格不会跑偏。后续如果你想继续折腾还可以研究一下图片压缩、目录自动生成、更多代码高亮主题接入这些扩展方向工具本身的设计余量还是比较充足的。
阅读完成 · 觉得有帮助？
