WeMD 一键复制公众号链路深度拆解:5个保真原理,公式图表不翻车
WeMD 一键复制公众号链路深度拆解:5个保真原理,公式图表不翻车
WeMD 是一款更优雅的 Markdown 公众号编辑器,主打"Markdown 写作、一键复制到公众号"。很多人好奇:为什么它在 WeMD 编辑器里看着很精致的文章,粘贴到微信公众号后台后,主题色、公式、Mermaid 图表居然基本不翻车?🤔 答案藏在它复制前的那一串"预处理流水线"里——CSS 变量展开、公式图片化、Mermaid 图片化、DOM 规范化、多级剪贴板回退。本文带你完整拆解这条链路的核心原理,不堆代码,讲清每一步"为什么这么干"。
一、一键复制到底要对抗什么?
先把问题说透。微信公众号编辑器对粘贴进来的 HTML 有一道"清洗"工序,它会:
| 微信清洗行为 | 不处理的后果 |
|---|---|
不支持 CSS 变量 var(--*) |
主题色整体丢失,文章变"素颜" |
| 剥离隐藏 MathML、伪元素 | 公式暴露出 TeX 源码 |
| 清掉最外层容器的 padding/背景 | 页边距消失、连续背景断裂 |
| 不渲染 Mermaid 代码块 | 读者看到一堆 graph TD 源码 |
| 不转存 45×13 这类超小 data URI | 小图标保存草稿时被抹掉 |
所以"一键复制"的本质不是复制,而是复制前把 HTML 改造成微信"洗不掉"的形态。这条流水线的编排入口是 copyToWechat,它在一个 760px 的离屏容器里跑完所有步骤,才真正写入剪贴板。
二、链路全景:从 Markdown 到剪贴板的 8 步
Markdown 源码
→ ① Markdown 解析(KaTeX 公式、GFM 扩展)
→ ② CSS 变量展开(主题 CSS + 内联 style 双通道)
→ ③ juice 内联样式(<style> → 元素 style 属性)
→ ④ counter 伪元素实体化(CSS 计数器 → 真实文本)
→ ⑤ 高危公式 MathJax 渲染成 SVG 图片
→ ⑥ Mermaid 代码块渲染成 3x PNG 图片
→ ⑦ 容器规范化(padding 迁移、背景下沉、颜色实体化)
→ ⑧ 多级剪贴板写入(execCommand → Electron → Clipboard API)
每一步失败都有降级方案,保证"最坏情况也只是少一点美化,而不是整篇失败"。下面挑最核心的三个模块细讲。
三、CSS 变量展开:为什么微信不认 var()?
主题 CSS 里大量使用 var(--wemd-*) 这类自定义属性,这是现代 CSS 的优雅写法——但微信编辑器不支持。如果原样复制过去,所有依赖变量的颜色、圆角、间距瞬间失效。
WeMD 的解法是 expandCSSVariables:在纯文本层面做变量展开,完全不依赖运行时 DOM。
展开三步走:
- 提取——逐字符扫描 CSS(正确处理引号、转义、注释),收集所有
--*变量声明,见 cssVarParser; - 递归替换——把所有
var(--xxx)引用替换成具体值。支持 fallback 值(var(--a, red)),并用"正在解析集合"防止变量互相引用造成的死循环,核心实现是 resolveVarReferences; - 清理——展开完成后,把
--*声明本身从 CSS 里删掉,因为微信根本不认识它们。
但只展开主题 CSS 还不够。 juice 把 CSS 内联到元素 style 属性后,style 里可能还残留 var()(比如内联自定义属性)。这时 resolveInlineStyleVariablesForCopy 会遍历整棵元素树,逐个元素把变量解析成具体值,并强制使用"亮色主题变量"——避免你在深色 UI 下复制,结果复制出一套暗色文字。
内联阶段的主力是 processHtml,它用 juice 把主题 CSS 全部塞进元素 style 属性,同时顺手保护代码块里的缩进空格(转成 ),防止被微信"洗"掉。
四、公式图片化:KaTeX 之外,MathJax 兜底
普通公式由 KaTeX 渲染成 HTML,速度快、效果好。但 KaTeX 的产物里藏着"隐患":它输出的隐藏 MathML 与 TeX annotation 会被微信清洗后暴露成肉眼可见的源码。
WeMD 分两手处理(wechatMathCompat):
第一手:高危公式升级成 SVG 图片。 renderHighRiskMathAsImages 会找出所有带 data-latex 的公式节点,按需加载 MathJax(带 4 秒超时),用 tex2svg 把公式渲染成内联 SVG:
- 黑色的
fill/stroke统一改写成currentColor,让公式颜色跟随主题; - 渲染失败不阻断复制,自动降级为
$latex$纯文本源码——不美观但绝对保活,这是"可用性优先于美观"的典型取舍; - 单篇中每降级一个公式,复制完成后的提示语会如实告诉你"已降级为源码"。
第二手:拆弹。 stripHiddenMathMarkupForWechat 移除所有隐藏的 MathML 节点与 annotation,并给 KaTeX 节点追加 white-space: nowrap 等内联保险,防止公式在微信里被换行折断。
五、Mermaid 图片化:SVG → 3x 高清 PNG
公众号里 pre.mermaid 代码块只会显示源码,Mermaid 官方脚本在微信环境也跑不起来。WeMD 的策略是在浏览器端把图表预先画成 PNG,核心在 renderMermaidBlocks。
完整过程有几个精巧的细节:
- 主题联动:通过 mermaidConfig 把当前主题的主色、字体注入 Mermaid 配置,图表配色自动跟随主题;
- foreignObject 替换:Mermaid 默认用 HTML 标签(foreignObject)渲染文字,这种元素画进 canvas 会"污染"画布导致导出失败。WeMD 在 wechatMermaidSvgText 里把 HTML 标签逐个换算成原生 SVG
text节点,连 subgraph 标题都做了坐标补偿; - 3 倍分辨率渲染:svgMarkupToPng 把 SVG 序列化后经 Blob URL 加载(规避跨域污染),在 3 倍尺度的 canvas 上先铺白底再绘制——白底是为了防止微信深色模式下透明背景导致文字不可读;
- 优雅降级:PNG 转换万一失败,降级为内联 SVG,"至少比裸露源码强"。
六、容器规范化:让留白和背景"洗不掉"
图片化之后,还有一层 DOM 层面的加固——normalizeCopyContainer:
- padding 迁移:微信会清掉最外层容器的 padding,所以复制前把根节点的左右留白"下沉"到每个一级内容块上(标题、引用块改用 margin,避免边框贴边);
- 背景下沉:根元素的背景色被提取后,逐个写到子块的内联 style 上,让整篇文章背景色不再依赖外层容器;
- 颜色实体化:把继承来的
color写成具体值,消除inherit/currentColor这类微信算不准的关键字; - 元数据清理:移除
data-tool等编辑器内部标记,保持粘贴内容干净。
另有几个"小补丁"值得一提:代码块换行被 materializeCodeLineBreaksForWechat 实体化为 <br>;CSS 计数器伪元素(counter() 自动编号)在复制前由 wechatCounterCompat 直接算成真实文本;Mac 窗口圆点这类 45×13 的小图,因为微信不转存超小 data URI,会被替换为托管外链图片(源码注释)。
七、剪贴板写入:三级回退策略
最后一步写入剪贴板,WeMD 按平台特性选择最优通道:
- 选区复制 + copy 事件注入:通过
execCommand("copy")触发浏览器选区序列化,普通主题直接沿用;需要精确 HTML 的场景(如连续背景图)则在 copy 事件里preventDefault并手动写入完整 HTML; - Electron 原生剪贴板:桌面端在 macOS/Linux 上优先走原生桥接(Windows 除外,Windows 与手动复制一致的选区链路更稳);
- Clipboard API:前两者都失败时,用
ClipboardItem写text/html+text/plain双通道兜底。
复制成功后,提示语会根据公式处理结果区分三种文案,让你清楚知道这篇文章的公式是"完整保真"还是"部分降级"。如果你只是想拿一段干净的 HTML 去别的编辑器,copyAsHtml 提供了一条不走微信适配、只做结构清洗的轻量链路。
八、核心源码文件速查
想继续深入,可以从这几个文件入手:
| 模块 | 文件 | 职责 |
|---|---|---|
| 复制主编排 | wechatCopyService.ts | 串联全部步骤与剪贴板策略 |
| CSS 变量展开 | cssVariableExpander.ts | 纯文本级 var() 递归展开 |
| 内联变量解析 | inlineStyleVarResolver.ts | 元素树级变量解析 + 亮色变量注入 |
| 样式内联 | ThemeProcessor.ts | juice 内联 + 代码块空格保护 |
| 公式兼容 | wechatMathCompat.ts | MathJax SVG 图片化与降级 |
| Mermaid 渲染 | wechatMermaidRenderer.ts | SVG → 3x PNG 全链路 |
| 容器规范化 | wechatCopyNormalizer.ts | padding/背景/颜色加固 |
九、总结
WeMD 一键复制的精髓,可以浓缩成三句话:
- 能算的提前算——CSS 变量、计数器编号、颜色继承,全部在复制前解析成"死值",不给微信留下清洗空间;
- 能画的提前画——高危公式和 Mermaid 图表在浏览器里就变成 SVG/PNG,粘贴即所见;
- 每步都有退路——公式降级为源码、Mermaid 降级为内联 SVG、剪贴板三级回退,任何单点故障都不至于让复制失败。
这套"预处理优先 + 优雅降级"的工程思路,不只适用于公众号,对任何向封闭渲染环境输出富文本的场景都有参考价值。✨
