一起用 Python 给自己写个微信公众号文章排版工具,从此公众号排版不求人

本文适用于Python编程学习者、开发者，以及有 Python 基础、想自己做公众号文章排版工具的创作者。文后附完整源代码获取方式。

写公众号文章，自然就会碰到公众号文章排版的问题，之前我是一直用网上一个在线的基于Markdown编辑、公众号排版平台。最近，突然想“自己学习Python编程，不如自己做个公众号排版工具（脚本）吧”。于是就动手做了本文的这个公众号排版工具。

本文假定读者具备：Python基础语法、正则表达式基础、HTML基础等。

我自己对这个工具的要求不高，简约，实用就行。不用花哨、复杂的功能，就是简单的排版。基于此，计划实现：

1. 完成一个可直接使用、可扩展的公众号排版脚本（代码和模板分离）
2. 熟悉微信 HTML 机制

设计思路

本文开发的 Python 脚本设计思路如下：

1. 使用编辑软件（如 Typora / VS Code等）编辑 Markdown 文档格式公众号文章
2. 编写Python脚本将Markdown格式文章按微信公众号接受的规则转化成HTML格式文件
3. 使用浏览器打开并复制HTML格式文件的内容，粘贴到微信公众号文章编辑器中、检查修改、发布。

公众号排版工具整体结构如下：

---

公众号文章编辑器HTML解析规则简介

微信公众号编辑器其实是一个富文本编辑器。它接收 HTML 格式的内容，处理后再渲染。但它在处理 HTML 时有自己的规则，我们不能完全按照浏览器标准来写 HTML，要用"微信支持的子集"来写。经过多次实测，及网上已有资料，得到微信编辑器支持的一些HTML规则如下：

可靠支持的元素包括：

• 基础块级元素：<p>、<h1>-<h6>、<ul> / <ol> / <li>、<blockquote>、<table>、<pre>、<hr>
• 行内元素：<strong>、<em>、<code>、<a>、<span>、<br>
• 内联样式 style="..."
• border、background、color、font-size、padding、margin、border-radius、line-height 等常用属性
• <style> 标签内的简单类选择器

不支持 / 会丢掉的元素：

• @media 媒体查询
• ::before、::after（伪元素）
• :nth-child、:nth-of-type 等结构化伪类
• colgroup、thead、tbody（表格分组标签）
• 部分版本的 white-space:pre 失效（需要 pre-wrap 代替）

内联样式优先:

转化时需要注意的是：微信公众号编辑器粘贴时，解析器的核心工作是把样式从 <style> 和 class 中剥离并尽可能保留。但内联样式 style="" 是跟着标签走的，"清洗"时最容易保留。

贯穿整个工具的一个核心原则：

• 所有需要微信显示的样式，一律写成内联 style=""
• <style> 块只作为浏览器预览的补充，不依赖它

Markdown 向 HTML 转换 

本排版工具需要把常见的 Markdown 语法映射为带样式的 HTML，具体的映射关系见下表：

Markdown	HTML
# 标题  ~ ###### 标题	<h1>  ~ <h6>
**加粗**	<strong>
*斜体*	<em>
`行内代码`	<code>
围栏代码块 ```python	<pre><code>
> 引用	<blockquote>
- 列表	<ul><li>
1. 列表	<ol><li>
[链接](url)	<a href="url">
| 表 |	<table><tr><th/td>
---	<hr>

需要注意的是转化目标不是标准的HTML，而是微信能识别的HTML。

---

Python脚本的代码层次结构

在开发这个排版工具的时候，我把 Python 代码分为三个层次模块（都在同一个文件里）：

Python文件名：wechat_formatter.py┌─────────────────────────────────────────────┐│ 1. 风格层                                    ││    Style 类 + styles/*.json 加载            ││    - 颜色、字号、装饰配置                    ││    数据与代码分离（22 种内置风格）            │├─────────────────────────────────────────────┤│ 2. 核心引擎（Formatter 类）                  ││    - Markdown 逐行解析（状态机）             ││    - 语法高亮、内联样式化                    ││    - 微信兼容性处理                          │├─────────────────────────────────────────────┤│ 3. 入口层                                    ││    - argparse 命令行参数                     ││    - convert() 总管线                        │└─────────────────────────────────────────────┘

脚本的主要功能

本工具为命令行使用方式，具体用法及功能如下：

usage: python wechat_formatter.py [输入文件] [-s 风格名] [-o 输出] [-c 自定义风格]       python wechat_formatter.py --list-styles     # 显示所有风格       python wechat_formatter.py --list-decos      # 显示所有标题装饰       python wechat_formatter.py --export-defaults 目录  # 导出内置风格为 JSON

排版风格与Python代码分离设计

风格与代码分离是本工具最重要的可维护性设计：

style = {"name": "tech","accent": "#6d28d9",        # 主色"accent_light": "#f0e6ff",  # 浅主色"text_color": "#1e293b",    # 正文色# ... 约 20 个字段"title_decoration": "underline",  # h1 装饰"h2_decoration": "left-border",   # h2 装饰}

• styles/*.json 目录存风格文件
• load_styles() 读取目录并构建 Style 对象
• _builtin_styles() 内置 22 个作为安全回退
• 新增风格 = 复制一个 JSON 改颜色，不需要改代码

核心算法

Style 类与 JSON 加载

classStyle:"""风格配置数据类，承载全部颜色/字号/装饰配置"""def__init__(self, name, label, desc,                 accent, accent_light, text_color, heading_color,                 link_color, body_bg, code_bg, code_border,                 code_header_bg, quote_bg, quote_text,                 table_header_bg, table_border, table_stripe,                 hr_color, highlight_bg_start, highlight_bg_end,                 font_family="",                 title_decoration="none", h2_decoration="none",                 h3_decoration="none", h4_decoration="none",                 h5_decoration="none", h6_decoration="none",                 h2_font_size="", h3_font_size="", h4_font_size="",                 h5_font_size="", h6_font_size=""):# ...（字段赋值略）

style_from_dict() 把 JSON dict 映射为 Style；style_to_dict() 反之，用于 --export-defaults。

风格加载

defload_styles(style_dir=None):"""加载风格：优先读 styles/*.json，找不到用内置默认"""    d = (Path(style_dir) if style_dir else _default_styles_dir())    styles = {}if d.is_dir():for f in sorted(d.glob("*.json")):try:                data = json.loads(f.read_text(encoding="utf-8"))                styles[data["name"]] = style_from_dict(data)except Exception:                print(f"[警告] 跳过损坏的风格文件: {f}")# 补全未提供的内置风格for name, st in _builtin_styles().items():        styles.setdefault(name, st)return styles

行内格式处理与 HTML 转义

@staticmethoddef_inl(t: str) -> str:# 第一步：转义 HTML 特殊字符（真实 bug 修复）    t = html.escape(t)          # < > & " '  → 实体# 第二步：保护行内代码，防止 * _ [ ] 被后续正则二次处理    codes = []    t = re.sub(r"`([^`]+)`", lambda m: (        codes.append(m.group(1)) orf"\x00CODE{len(codes)-1}\x00"), t)# 第三步：行内标记转 HTML（加粗、斜体、删除线、链接）    t = re.sub(r"\*\*([^*]+)\*\*([：:，,。.、；;！!？?）)]?)",lambda m: f"<strong>{m.group(1)}{m.group(2)}</strong>", t)# ... 斜体、删除线、链接# 第四步：还原行内代码for n, code in enumerate(codes):        t = t.replace(f"\x00CODE{n}\x00", f"<code>{code}</code>")return t

说明：

顺序：先 html.escape() 转义所有 <>、&、引号，再处理行内标记。这样正文里出现 <div> 也会被转成 <div>，不会干扰微信解析。

占位符保护：行内代码内容如果含星号（例如 a * b * c），直接替换成 <code> 标签后，后续斜体正则会把 * 再次处理成 <em>，导致标签错乱。先用不可见占位符替代，最后还原，保证代码内容原样输出。

语法高亮 + 空格保留

代码块的处理是这个工具里比较重要的部分，说是重要，是因为，在工具开发，格式转化时，我发现代码内的空格会被忽略， 比如 def xxx:，def和 xxx中间的空格会被公众号文章编辑器给忽略，导致变成defxxx，所以需要专门的处理。示例代码如下：

def_cc(self):if self._code:        lines = self._clif self._la == "python":            hl_lines = []for line in lines:                indent = re.match(r"^\s+", line)if indent:                    indent_nbsp = "&nbsp;" * len(indent.group(0))                    rest = self._hl(line[len(indent.group(0)):])                    hl_lines.append(indent_nbsp + self._spaces_to_nbsp_in_text(rest))else:                    hl_lines.append(self._spaces_to_nbsp_in_text(self._hl(line)))            hl = "\n".join(hl_lines)else:            hl = html.escape("\n".join(lines)).replace(" ", "&nbsp;")# 背景/边框全写在 <pre> 内联样式（避免 div class 被剥）        self._e('<pre style="margin:16px 0;padding:16px;overflow-x:auto;''white-space:pre-wrap;word-break:break-all;'f'background:{self.st.code_bg};border:1px solid 'f'{self.st.code_border};border-radius:6px;...">'f"<code>...{hl}...</code></pre>\n"        )        self._cl = []        self._code = False

注意事项：

1. 缩进：行首空格 →  （否则微信合并连续空格）
2. 行内空格：return True 中的空格 →  （否则变成 returnTrue）
3. 只在文本节点替换：_spaces_to_nbsp_in_text 用正则切出标签与非标签段，只替换标签外的空格，避免破坏 <span style="...">
4. 背景色上 <pre>：微信会剥 <div>，但 <pre> 的内联样式基本可靠

表格

if s.startswith("|") and s.endswith("|"):if re.match(r"^[\|:\-\s]+$", s):return# 分割行，跳过    self._cp(); self._cll(); self._cb()    cells = [self._inl(c.strip()) for c in s.strip("|").split("|")]    tag = "th"ifnot self._in_table else"td"    inner = f"</{tag}><{tag}>".join(cells)    self._e(f"<tr><{tag}>{inner}</{tag}></tr>\n")

微信公众号文章编辑器不支持 nth-child，所以交替行背景色直接写在 <tr> 的内联样式上——这是我本次测试发现的问题之一。

实施步骤

我本次开发这个排版工具的从零搭建的全部过程如下：

1. 准备工作

mkdir wechat-formattercd wechat-formattermkdir stylespip install pygments   # 唯一外部依赖（用于语法高亮）

2. 完成 最简单的 Markdown 转换

第一步只需要实现：读取文件 → 逐行判断 → 标题/段落 → 输出 HTML。目标不追求完美，但要能跑通。

最小可运行版本验证思路：Markdown → HTML → 浏览器显示。

3. 加样式：引入 Style 与 JSON

把配色抽成 JSON，添加 --list-styles。此时"风格与代码分离"的构架开始成形。

4. 加代码高亮与表格

引入 Pygments，_hl() / _tk() 实现 GitHub 浅色高亮；表格通过 _in_table 标志 + _ct() 精确定闭合。

5. 加标题装饰

引入 decor 装饰系统（_deco_css_props + _wrap_heading），h1~h6 各自可配：

• CSS 类装饰（underline、left-border、dot-underline、block-radius、light-bg、short-line、stripe-bg、underline-accent、bg-label、center-line）：通过 _deco_css_props() 返回 CSS 属性串，渲染时内联到对应标题
• HTML 类装饰（circle-left、dot、triangle、number、flag）：通过 _wrap_heading() 插入真实 <span> 元素，微信完全支持
• 新增一种装饰只需修改 _deco_css_props()（CSS 类）或 _wrap_heading()（HTML 类），其余代码不动

6. 微信公众号编辑器HTML兼容性

这是我本工具开发投入最多时间的环节。把生成 HTML 在微信里实测，反复修改、测试，几个问题及解决方法见下表：

7. 命令行用法说明

python wechat_formatter.py 文章.md -s tech          # 排版python wechat_formatter.py 文章.md -s forest -o out.htmlpython wechat_formatter.py --list-stylespython wechat_formatter.py --list-decos# 自定义风格# 编写配色方案，如：styles/mine.json，命令行如下：python wechat_formatter.py 文章.md -s mine

输出 HTML 后：

1. 浏览器打开
2. Ctrl+A 全选 → Ctrl+C
3. 粘贴到微信编辑器
4. 预览 → 发布

完整源码获取方法：关注后发生“mdformatter”，获取下载地址。