WeMD 一键复制公众号链路深度拆解:5个保真原理,公式图表不翻车

原创2026-10-22 23:11:501,877 阅读

WeMD 一键复制公众号链路深度拆解:5个保真原理,公式图表不翻车

WeMD 是一款更优雅的 Markdown 公众号编辑器,主打"Markdown 写作、一键复制到公众号"。很多人好奇:为什么它在 WeMD 编辑器里看着很精致的文章,粘贴到微信公众号后台后,主题色、公式、Mermaid 图表居然基本不翻车?🤔 答案藏在它复制前的那一串"预处理流水线"里——CSS 变量展开、公式图片化、Mermaid 图片化、DOM 规范化、多级剪贴板回退。本文带你完整拆解这条链路的核心原理,不堆代码,讲清每一步"为什么这么干"。

WeMD Markdown 公众号编辑器界面:左侧历史文章列表、中间 Markdown 编辑器、右侧实时预览

一、一键复制到底要对抗什么?

先把问题说透。微信公众号编辑器对粘贴进来的 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。

展开三步走:

  1. 提取——逐字符扫描 CSS(正确处理引号、转义、注释),收集所有 --* 变量声明,见 cssVarParser;
  2. 递归替换——把所有 var(--xxx) 引用替换成具体值。支持 fallback 值(var(--a, red)),并用"正在解析集合"防止变量互相引用造成的死循环,核心实现是 resolveVarReferences;
  3. 清理——展开完成后,把 --* 声明本身从 CSS 里删掉,因为微信根本不认识它们。

但只展开主题 CSS 还不够。 juice 把 CSS 内联到元素 style 属性后,style 里可能还残留 var()(比如内联自定义属性)。这时 resolveInlineStyleVariablesForCopy 会遍历整棵元素树,逐个元素把变量解析成具体值,并强制使用"亮色主题变量"——避免你在深色 UI 下复制,结果复制出一套暗色文字。

内联阶段的主力是 processHtml,它用 juice 把主题 CSS 全部塞进元素 style 属性,同时顺手保护代码块里的缩进空格(转成 &nbsp;),防止被微信"洗"掉。

四、公式图片化: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 按平台特性选择最优通道:

  1. 选区复制 + copy 事件注入:通过 execCommand("copy") 触发浏览器选区序列化,普通主题直接沿用;需要精确 HTML 的场景(如连续背景图)则在 copy 事件里 preventDefault 并手动写入完整 HTML;
  2. Electron 原生剪贴板:桌面端在 macOS/Linux 上优先走原生桥接(Windows 除外,Windows 与手动复制一致的选区链路更稳);
  3. 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 一键复制的精髓,可以浓缩成三句话:

  1. 能算的提前算——CSS 变量、计数器编号、颜色继承,全部在复制前解析成"死值",不给微信留下清洗空间;
  2. 能画的提前画——高危公式和 Mermaid 图表在浏览器里就变成 SVG/PNG,粘贴即所见;
  3. 每步都有退路——公式降级为源码、Mermaid 降级为内联 SVG、剪贴板三级回退,任何单点故障都不至于让复制失败。

这套"预处理优先 + 优雅降级"的工程思路,不只适用于公众号,对任何向封闭渲染环境输出富文本的场景都有参考价值。✨

登录后查看全文
WeMD