如何使用Python将HTML网页内容保存为本地Markdown文件

html2text 是最稳的 HTML 转 Markdown 方案，需配置 ignore_links=False、body_width=0、single_line_break=False、skip_internal_links=True、protect_links=True，并处理表格、代码块及隐形字符，预处理 HTML 才能保障质量。

直接用 html2text 是最稳的路径，但默认行为会把链接、代码块、表格全搞乱——得手动调参数，否则生成的 .md 文件根本没法读。

为什么不用 BeautifulSoup + 手动解析？

因为 HTML 结构千变万化：blockquote 嵌套 ul、pre 里混着 code、自定义 class 的标题……手动映射标签到 Markdown 语法极易漏 case，维护成本高。而 html2text 已覆盖主流语义标签（h1–h6、table、dl 等），只要调对选项，就能省掉 90% 的边界判断。

html2text 的关键配置项必须设

默认输出是为终端设计的，不是为 Markdown 编辑器或静态站点生成器准备的。不改这些，生成的文件大概率要重写：

• parser.ignore_links = False：否则所有 <a href="...">文本</a> 都变成纯文本，丢掉链接
• parser.body_width = 0：禁用自动换行，否则长段落被切成多行，破坏 Markdown 段落语义
• parser.single_line_break = False：避免把单个 <br> 渲染成 n，导致多余空行
• parser.skip_internal_links = True：过滤掉 #section-id 这类页面内跳转，不然生成一堆无效锚点
• parser.protect_links = True：防止 URL 被错误地截断或转义（尤其含中文或查询参数时）

遇到表格和代码块怎么办？

html2text 对 <table> 默认输出 ASCII 表格（用 | 和 -），但 GitHub Flavored Markdown 要求表头下必须有分隔行，且单元格内不能有换行。解决方案：

立即学习“Python免费学习笔记（深入）”；

• 表格：加 parser.table_grid = True 强制使用网格格式，比 table_spaces 更兼容主流解析器
• 代码块：确保原始 HTML 中 <pre><code class="python">... 结构完整；html2text 会自动识别 class 并输出 ```python``` 语法高亮标记
• 如果页面用了非标准 class（如 lang-js），需提前用 BeautifulSoup 重写 class 名，再喂给 html2text

保存前记得清理不可见字符和多余空白

网页常含零宽空格（u200b）、NBSP（xa0）、连续空行——这些在 Markdown 里不报错但影响阅读。建议在写入文件前做两件事：

• 用 re.sub(r'[u200bu200cu200du2060ufeffxa0]+', ' ', text) 替换所有隐形空白符
• 用 re.sub(r'n{3,}', 'nn', text) 把超过两个连续换行压成两个，保持段落间距合理
• 文件编码必须显式指定为 utf-8，否则中文标题或符号可能乱码

真正麻烦的不是转换本身，而是 HTML 源是否规范：JS 渲染的内容、懒加载图片的占位符、广告脚本插入的垃圾节点……这些都得在喂给 html2text 前用 BeautifulSoup 先切掉 script、style、nav、footer 等无关区域。没这步预处理，生成的 Markdown 里大概率混着“undefined”或者一堆乱码 div class。