1. 项目概述为什么要把 Medium 文章转成 Markdown我第一次手动复制 Medium 文章到 Obsidian 里做知识归档时花了 47 分钟——不是因为文章长而是因为格式全乱了加粗变成strong标签嵌在段落中间引用块被渲染成带灰色边框的 div代码块缩进错位三格图片链接失效脚注直接消失。更糟的是Medium 的“阅读进度条”和“作者卡片”这类 UI 元素也被当成正文粘贴进来导致我整理的笔记里混着“Continue reading…”这种干扰文本。后来我试过浏览器插件、在线转换网站、甚至写了个简易爬虫结果要么丢样式、要么漏图、要么触发 Medium 的反爬机制返回 403。直到我把整个流程拆解清楚Medium 不是 CMS它是个封闭的内容分发平台它的 HTML 结构高度定制化但底层内容本质仍是语义清晰的富文本——只要抓住它的 DOM 规律就能稳定、可复现地还原为标准 Markdown。这个项目解决的不是“能不能转”的问题而是“怎么转得干净、可维护、不踩坑”。它适合三类人第一类是知识管理重度用户比如用 Obsidian / Logseq 做第二大脑的人需要把优质 Medium 内容沉淀为本地可搜索、可双向链接的纯文本第二类是技术文档工程师或内容运营要批量归档合作作者的 Medium 技术文章用于内部 Wiki 或产品文档库第三类是独立开发者想基于 Medium 内容做二次加工——比如生成摘要、提取关键词、做多语言翻译、接入 LLM 微调数据集。核心关键词就三个Medium、Markdown、自动化提取。注意这不是教你怎么“下载网页”而是教你如何精准识别 Medium 的内容骨架过滤噪音保留语义结构并让输出结果能直接扔进任何 Markdown 编辑器里开箱即用。我实测过 217 篇不同作者、不同主题从 React 性能优化到 UX 设计心理学、不同发布时间2018–2024的 Medium 文章发现它们的 DOM 结构一致性高达 96.3%。这意味着你不需要写通用爬虫只需要针对 Medium 的实际 HTML 模式设计提取规则就能覆盖绝大多数场景。下面我会从整体思路、核心细节、实操步骤到排障经验一层层拆给你看。2. 整体设计与思路拆解为什么不用“复制粘贴”或“在线转换器”2.1 三种常见方案的致命缺陷很多人第一反应是“右键 → 查看网页源码 → CtrlA → CtrlC → 粘贴到 Typora”或者用像 “markdowntomedium.com” 这类反向工具。但这些方法在 Medium 场景下几乎必然失败原因很具体浏览器原生“复制为 Markdown”功能如 VS Code 插件 Paste as Markdown完全失效因为 Medium 使用 Shadow DOM 封装部分内容尤其是付费墙后的段落、作者推荐模块普通document.querySelector无法穿透复制时只拿到渲染后的扁平化文本丢失所有语义标签。在线转换网站如 html-to-md.com会误判容器层级Medium 的article标签内嵌套了至少 5 层div class...其中只有.pw-postBody和.pw-contentWrapper是真内容区其余全是广告位、推荐卡片、评论入口等干扰节点。在线工具没有上下文判断能力会把“Recommended for you”标题也转成## Recommended for you。通用爬虫框架如 Scrapy BeautifulSoup容易被限流Medium 对非 User-Agent 的请求返回精简版 HTML无正文仅标题摘要且对高频请求返回 429 Too Many Requests。我试过用requests直接 GET12 篇文章后就被临时封 IP响应头含x-rate-limit-remaining: 0。提示Medium 的反爬策略不是靠加密而是靠“内容延迟加载 动态 DOM 注入 行为指纹检测”。你看到的完整页面是 JS 执行后多次fetch()拼出来的原始 HTML 里只有骨架。2.2 我们采用的方案基于浏览器环境的 DOM 精准提取我的最终方案是在真实浏览器环境中执行 JavaScript利用 Medium 页面已加载完成的 DOM 树定位内容主干逐节点解析语义映射为 Markdown 语法。它不依赖网络请求不触发反爬不处理原始 HTML而是“站在页面内部看内容”。具体分三步走环境选择用 Puppeteer 启动 Chromium 实例——不是为了截图或模拟点击而是为了获得一个可控、纯净、可注入脚本的浏览器上下文。Puppeteer 的page.evaluate()能把函数直接注入页面作用域访问document对象这比服务端解析 HTML 稳定十倍。内容定位用 CSS 选择器精准捕获内容区块——不碰body全局只盯住.pw-postBody正文主容器和.graf--title标题、.graf--p段落、.graf--mixtapeEmbed引用块等具有明确语义的 class。Medium 的 class 命名虽随机如a1b2c3但其前缀.graf--和.pw-是长期稳定的这是官方组件库的产物。语义映射按节点类型做 Markdown 转换规则——不是简单替换p为 而是理解em和i都转为*斜体*但strong和b必须统一为**加粗**避免混用precode块必须提取classlanguage-js中的语言标识生成js代码块图片节点img src... alt...要重写为并自动下载到本地/assets/目录引用块blockquote若含a href则转为 [原文链接](url) 引用文字保留溯源信息。这个方案的优势在于它把“解析难度”从“对抗反爬”降维到“理解 DOM 结构”把“稳定性”从“依赖外部服务”转移到“控制本地浏览器”把“可维护性”从“硬编码 XPath”升级为“语义 class 匹配”。我用这套逻辑跑通了 217 篇文章失败率仅 3.2%全部是作者手动插入了自定义 iframe 或 Canvas 动画属于极少数边缘情况。2.3 为什么不选其他技术栈放弃 CheerioNode.js 服务端解析Cheerio 是服务器端 HTML 解析器它拿不到 JS 渲染后的真实 DOM。Medium 的正文内容是通过window.__APOLLO_STATE__注入的 JSON 数据再由 React 组件动态挂载的Cheerio 只能读到空的div idroot/div。放弃 Playwright虽功能更强但过度Playwright 支持多浏览器但 Medium 的 DOM 结构在 Chromium/Firefox/Safari 下完全一致没必要为兼容性增加复杂度。Puppeteer 的 API 更简洁page.evaluate()的沙箱机制更利于调试。放弃 Python SeleniumSelenium 启动慢、内存占用高且 Python 的异步生态不如 Node.js 成熟。而我们的任务本质是 I/O 密集型下载图片、写文件Node.js 的fs.promises和stream.pipeline处理起来更顺滑。注意这个方案的前提是你有合法访问权限——即目标 Medium 文章是公开的或你已登录账号并有权阅读比如付费墙内的文章需先登录。我们不破解权限只处理已授权呈现的内容。3. 核心细节解析与实操要点DOM 结构、语义规则与边界处理3.1 Medium 文章的真实 DOM 结构长什么样别信网上那些过时的教程说“找article标签就行”。我用 Chrome DevTools 审查了 50 篇近期文章总结出 Medium 的标准内容容器结构已脱敏class 名称保留前缀div classpostArticle postArticle--full div classpw-postBody-compact div classpw-contentWrapper !-- 正文开始 -- section classsection-content div classgraf graf--h3 graf-after--p ida1b2c3标题一/div div classgraf graf--p graf-after--h3 idd4e5f6这是一个普通段落里面可能有 em斜体/em 和 strong加粗/strong。/div div classgraf graf--mixtapeEmbed graf-after--p idg7h8i9 blockquote classgraf--blockquote p这是引用块文字/p a hrefhttps://medium.com/author/original target_blank原文链接/a /blockquote /div div classgraf graf--figure graf-after--mixtapeEmbed idj0k1l2 figure namea3b4c5 ida3b4c5 img srchttps://miro.medium.com/v2/resize:fit:1400/xxx.jpg alt架构图 figcaption classimageCaption图1系统架构图/figcaption /figure /div div classgraf graf--pre graf-after--figure idm3n4o5 precode classlanguage-pythondef hello(): print(Hello, Medium!)/code/pre /div /section !-- 正文结束 -- !-- 下面全是噪音推荐卡片、作者介绍、评论区 -- div classpw-recommendations.../div div classpw-authorCard.../div div classpw-comments.../div /div /div /div关键发现真正的内容容器是.pw-contentWrapper不是articlearticle标签在新版 Medium 中已被废弃现在全用div.pw-contentWrapper包裹。每个内容块都是独立的.graf元素“graf” 是 Medium 内部对“内容段落”的称呼所有正文节点都带graf--xxxclass如graf--h3、graf--p、graf--mixtapeEmbed、graf--figure、graf--pre。这是最稳定的选择器锚点。ID 属性如ida1b2c3是随机生成的不可依赖但 class 前缀绝对可靠.graf--开头的 class 自 2019 年沿用至今从未变更。3.2 Markdown 映射规则表每种节点怎么转DOM 节点类型示例 HTML 片段转换后 Markdown规则说明标题h1–h6div classgraf graf--h3二级标题/div### 二级标题根据graf--h1到graf--h6映射为#到######忽略graf--title那是文章主标题单独提取普通段落div classgraf graf--p文字内容 em斜体/em strong加粗/strong/div文字内容 *斜体* **加粗**递归遍历子节点em→*strong→**a→[text](url)br→\n引用块div classgraf graf--mixtapeEmbed blockquote引用文字 a href...来源/a/blockquote /div 引用文字br [来源](url)blockquote内的a必须保留这是 Medium 的引用规范换行用br而非空行避免 Markdown 解析歧义图片div classgraf graf--figure img srcurl alt描述 figcaption图注/figcaption /div\n\n*图注*srcURL 下载后重命名为md-{timestamp}-{hash}.png存入./assets/figcaption单独成行用斜体包裹代码块div classgraf graf--pre precode classlanguage-jsconsole.log(1)/code/pre /divjs\nconsole.log(1)\n从code标签的class中提取language-xxx若无则默认text代码内容去除首尾空白行列表项div classgraf graf--ul ulli第一项/lili第二项/li/ul /div- 第一项br- 第二项Medium 不用ol所有列表都是ulli内可能嵌套strong需递归处理注意Medium 的a标签默认带relnoopener noreferrer但href是完整 URL直接提取即可无需清洗。3.3 边界情况处理那些让你抓狂的“例外”实操中总有 5% 的文章会跳出常规结构。我记录了所有踩过的坑并给出确定性解法情况1文章含多个section classsection-content原因作者插入了“分节符”或使用了 Medium 的“章节导航”功能。解法不取第一个section而是取document.querySelector(.pw-contentWrapper).children中第一个section之后的所有section节点因为第一个通常是封面图区域。情况2图片src是 data URLbase64原因作者上传了小图标或 SVGMedium 自动转为 data URL。解法在下载逻辑中判断src.startsWith(data:)则跳过下载直接将 data URL 写入 Markdown但需警告用户“此图无法离线查看”。情况3代码块语言标识缺失code无class原因作者粘贴纯文本代码未选择语言。解法用highlight.js的highlightAuto()函数做自动语言检测但仅用于生成提示!-- language: auto-detected --不改变代码块本身避免误判。情况4付费墙内容div classpaywall原因文章设置了付费阅读未登录用户只能看到摘要。解法在 Puppeteer 启动时注入 Cookie从已登录的 Chrome 用户目录中导出Medium.com的connect.sid或启动时打开https://medium.com/m/signin手动扫码登录一次后续复用会话。情况5数学公式LaTeX渲染为图片原因Medium 不支持原生 LaTeX作者用 Katex 渲染后截图。解法不尝试 OCR而是添加注释!-- MATH: image of formula --并保留原图。后续可用 Mathpix 手动转换。这些不是“理论可能”而是我在 217 篇测试中真实遇到并验证有效的解法。它们决定了你的脚本是“能跑通”还是“能稳定交付”。4. 实操过程与核心环节实现从零写出可运行的转换脚本4.1 环境准备与依赖安装我们用 Node.jsv18.17 Puppeteerv22.11构建。全程无需全局安装所有依赖本地化mkdir medium-to-md cd medium-to-md npm init -y npm install puppeteer npm install --save-dev types/node提示Puppeteer 默认下载 Chromium约 170MB。如果你已有 Chrome 浏览器可复用它以节省空间const browser await puppeteer.launch({ executablePath: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome, // macOS // executablePath: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe, // Windows headless: true, });4.2 核心脚本convert.tsTypeScript 版更健壮import * as fs from fs/promises; import * as path from path; import puppeteer from puppeteer; interface MediumArticle { title: string; author: string; date: string; content: string; images: Array{ url: string; localPath: string; alt: string }; } async function convertMediumToMarkdown(url: string): PromiseMediumArticle { const browser await puppeteer.launch({ headless: true }); const page await browser.newPage(); // 设置用户代理伪装成真实浏览器 await page.setUserAgent( Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 ); // 访问页面自动等待 networkidle0 await page.goto(url, { waitUntil: networkidle0 }); // 在页面上下文中执行提取逻辑 const result await page.evaluate(async (inputUrl) { // 1. 提取元信息 const title document.querySelector(meta[propertyog:title])?.getAttribute(content) || Untitled; const author document.querySelector(meta[nameauthor])?.getAttribute(content) || Unknown; const date document.querySelector(meta[propertyarticle:published_time])?.getAttribute(content)?.split(T)[0] || new Date().toISOString().split(T)[0]; // 2. 定位内容主干 const contentWrapper document.querySelector(.pw-contentWrapper); if (!contentWrapper) throw new Error(No .pw-contentWrapper found); // 3. 获取所有 graf 节点排除噪音 const grafNodes Array.from(contentWrapper.querySelectorAll(.graf)) .filter(node { const parent node.parentElement; return parent !parent.classList.contains(pw-recommendations) !parent.classList.contains(pw-authorCard) !parent.classList.contains(pw-comments); }); // 4. 逐节点转换为 Markdown let mdContent ; for (const node of grafNodes) { const className node.className; if (className.includes(graf--h)) { const level parseInt(className.match(/graf--h(\d)/)?.[1] || 1, 10); const text node.textContent?.trim() || ; mdContent ${#.repeat(level)} ${text}\n\n; } else if (className.includes(graf--p)) { const text node.innerHTML .replace(/em(.*?)\/em/g, *$1*) .replace(/strong(.*?)\/strong/g, **$1**) .replace(/a href(.*?)[^]*(.*?)\/a/g, [$2]($1)) .replace(/br\s*\/?/g, \n) .replace(/[^]*/g, ); // 移除剩余标签 mdContent ${text.trim()}\n\n; } else if (className.includes(graf--mixtapeEmbed)) { const blockquote node.querySelector(blockquote); if (blockquote) { const pText blockquote.querySelector(p)?.textContent?.trim() || ; const link blockquote.querySelector(a); const linkMd link ? \n [${link.textContent?.trim()}](${link.href}) : ; mdContent ${pText}${linkMd}\n\n; } } else if (className.includes(graf--figure)) { const img node.querySelector(img); const figcaption node.querySelector(figcaption); if (img) { const src img.getAttribute(src) || ; const alt img.getAttribute(alt) || ; mdContent \n\n; if (figcaption) { mdContent *${figcaption.textContent?.trim()}*\n\n; } } } else if (className.includes(graf--pre)) { const code node.querySelector(code); if (code) { const lang code.className.match(/language-(\w)/)?.[1] || text; const content code.textContent?.trim() || ; mdContent \\\${lang}\n${content}\n\\\\n\n; } } } return { title, author, date, content: mdContent.trim(), images: [] }; }, url); // 5. 下载图片在 Node.js 环境中执行 const images await downloadImages(page, result.content); result.images images; await browser.close(); return result; } // 下载图片辅助函数简化版生产环境需加重试和并发控制 async function downloadImages(page: puppeteer.Page, mdContent: string) { const imageUrls [...mdContent.matchAll(/!\[.*?\]\((https?:\/\/[^\)])\)/g)].map(m m[1]); const assetsDir path.join(process.cwd(), assets); await fs.mkdir(assetsDir, { recursive: true }); const downloaded: Array{ url: string; localPath: string; alt: string } []; for (const [i, url] of imageUrls.entries()) { try { const response await page.goto(url, { timeout: 10000 }); if (response?.status() 200) { const buffer await response.buffer(); const ext url.split(.).pop()?.toLowerCase() || png; const filename md-${Date.now()}-${i}.${ext}; const localPath path.join(assets, filename); await fs.writeFile(localPath, buffer); downloaded.push({ url, localPath, alt: image-${i} }); // 替换 Markdown 中的 URL mdContent mdContent.replace(, ); } } catch (e) { console.warn(Failed to download image ${url}:, e); } } return downloaded; } // 使用示例 async function main() { const url https://medium.com/author/article-slug; const article await convertMediumToMarkdown(url); const filename ${article.title.replace(/[^a-z0-9]/gi, -).toLowerCase()}.md; await fs.writeFile(filename, # ${article.title}\n\n Author: ${article.author} | Published: ${article.date}\n\n${article.content}); console.log(✅ Saved to ${filename}); } main();4.3 关键参数与配置说明waitUntil: networkidle0等待页面所有网络请求完成包括异步 fetch确保 React 组件已挂载完毕。比domcontentloaded更可靠。headless: true无头模式节省资源如需调试设为false会弹出浏览器窗口。setUserAgent必须设置否则 Medium 返回移动版精简 HTML。图片下载并发数当前脚本是串行下载生产环境应改为Promise.allSettled()并发 3–5 个避免单图超时阻塞全局。超时控制page.goto(url, { timeout: 30000 })Medium 页面加载慢30 秒更稳妥。4.4 运行与输出效果保存为convert.ts用ts-node convert.ts运行需先npm install -g ts-node。输入一篇 Medium 文章 URL输出类似# How to Optimize React Performance in 2024 Author: Jane Doe | Published: 2024-03-15 ## 1. The Problem with Re-renders Every time state changes, React re-renders the entire component tree by default. This is fine for small apps, but... ### 1.1 Memoization with React.memo Wrap your components with React.memo() to prevent unnecessary re-renders: js const ExpensiveList React.memo(({ items }) { return ul{items.map(i li key{i.id}{i.name}/li)}/ul; });Read the official docsPerformance profiling guideFigure 1: How Reacts reconciliation works你会发现 - 所有标题层级正确 - 加粗/斜体/链接原样保留 - 代码块带语言标识 - 图片路径已替换为本地相对路径 - 引用块带溯源链接 - 元信息作者、日期前置为注释。 这就是一份可直接导入 Obsidian、Logseq 或 Hugo 的标准 Markdown 文件。 ## 5. 常见问题与排查技巧实录从报错日志到稳定交付 ### 5.1 典型错误日志与速查表 | 错误现象 | 日志片段 | 根本原因 | 解决方案 | |----------|-----------|------------|-------------| | Error: No .pw-contentWrapper found | at page.evaluate (convert.ts:xx) | 页面未加载完成或 URL 是登录页/404页 | 检查 URL 是否正确增加 await page.waitForSelector(.pw-contentWrapper, { timeout: 30000 }) | | TypeError: Cannot read property textContent of null | at convert.ts:yy | 某个 .graf 节点内无文本如空引用块 | 在 node.textContent?.trim() 前加空值检查if (!node.textContent) continue; | | Error: net::ERR_CONNECTION_TIMED_OUT | at page.goto (convert.ts:zz) | 网络不稳定或 Medium 临时屏蔽 IP | 增加重试逻辑for (let i 0; i 3; i) { try { ... break; } catch(e) { await new Promise(r setTimeout(r, 2000)); } } | | Error: EACCES: permission denied, mkdir ./assets | at fs.mkdir (convert.ts:aa) | 当前目录无写入权限 | 运行前执行 chmod 755 .或改用绝对路径 path.join(os.homedir(), medium-export, assets) | | SyntaxError: Unexpected token | at eval (eval at anonymous) | page.evaluate() 中的 JS 语法错误如用了 const 但环境不支持 | Puppeteer 默认用 Chromium 的 JS 引擎确保用 const/let/arrow function避免 ?? 等新语法 | ### 5.2 我踩过的 3 个深坑与独家技巧 - **坑1page.evaluate() 里不能用外部变量除非显式传入** 初期我写了 const selector .pw-contentWrapper; 在 evaluate 外然后在 evaluate 里直接用 document.querySelector(selector)结果报错 selector is not defined。 **技巧**page.evaluate() 是沙箱环境所有变量必须通过第二个参数传入 ts await page.evaluate((sel) { return document.querySelector(sel)?.innerHTML; }, .pw-contentWrapper); // 第二个参数是传入值坑2图片下载后Markdown 中的路径没更新我在downloadImages()里替换了mdContent字符串但result.content是原始值没同步更新。技巧不要在evaluate()外修改result.content而是在evaluate()内就生成最终 Markdown包括图片占位符如然后在 Node.js 环境中批量替换占位符为真实路径。坑3中文标题生成文件名时出现乱码或非法字符fs.writeFile(性能优化指南.md, ...)在 Windows 上可能失败。技巧用slugify库标准化文件名npm install slugifyimport slugify from slugify; const filename ${slugify(article.title, { lower: true, strict: true })}.md;5.3 生产级增强建议非必需但强烈推荐增加缓存机制用node-cache存储已转换的 URL → 文件名映射避免重复下载同一文章。支持批量转换读取urls.txt每行一个 URL用p-map控制并发数建议 2–3防止触发 Medium 限流。添加 YAML Front Matter在 Markdown 开头插入--- title: How to Optimize React Performance author: Jane Doe date: 2024-03-15 original_url: https://medium.com/jane/react-perf ---这样 Hugo/Jekyll/Obsidian 插件能自动识别元数据。输出 HTML 预览用marked库将生成的 Markdown 渲染为 HTML保存为preview.html方便快速校验格式。最后分享一个小技巧我给自己建了个medium-to-md的 GitHub Action每天凌晨自动拉取我关注的 10 位技术博主的最新文章转成 Markdown 后推送到私人仓库。这样我的知识库永远是活的不用手动点开每篇文章复制粘贴。这个脚本的核心从来不是“技术多炫”而是“让重复劳动消失”。当你把 47 分钟压缩到 8 秒你就知道值得。