简介MarkdownKit是一套用Swift编写的轻量Markdown解析器专为iOS与macOS开发者设计帮助在App内高效解析并展示标题、列表、链接等标准Markdown元素。解析内核基于正则表达式完成所有元素的字体、颜色等渲染属性均可按需调整适合需要为富文本展示统一风格的团队项目。资源包共69个文件压缩包仅120KB核心部分为39个Swift源文件同时包含plist配置、xcscheme工程方案、storyboard与xib界面布局以及png样例图片、ttf字体、podspec和Package.swift等多平台集成文件覆盖从源码阅读到实际接入的完整链路。目前已有291人学习下载尤其适合刚接触Swift富文本解析的初中级开发者也适合希望深度定制解析规则、封装内部Markdown渲染组件或研究正则表达式在文本处理中应用的工程师可从中直接复用解析流程、样式配置与安装集成方法其目录结构清晰分别组织源码、示例、配置与文档便于按需查阅和二次开发。 做iOS开发这些年Markdown渲染一直是个绕不过去的坎。很多场景下我们只是想把一段带#、*、反引号的文字在App里整洁地展示出来而不是把整个浏览器引擎搬进来。MarkdownKit就是我最常拿出来的一个纯 Swift Markdown 解析器它足够简单也留了足够的自定义空间。如果你正在写编辑器、聊天界面、富文本预览或者只是想把后台下发的长文转成结构化内容这篇文章里的思路和踩坑记录应该能帮你省不少事。我需要先说明一点这个库并不是对标完整 CommonMark 规范的庞然大物而是一个“够用且能改”的解析器。核心目标有三个不依赖 C 代码、节点可以自定义、性能在常规列表和段落文本上足够快。接下来我会从设计思路、解析流程、实际集成到问题排查完整拆一遍。1. 从“渲染”到“解析”先想清楚为什么造轮子很多人第一反应是Swift 生态里不是有swift-markdown吗Apple 官方的解析库干嘛还要自己写我当时的处境比较尴尬项目要支持 iOS 12又不想为了一个 Markdown 预览功能引入庞大的swift-markdown依赖而且官方库在解析时会生成非常完整的 AST处理起来对上层代码很不友好。我需要的是一个足够薄、行为透明、能让我在拿到节点后自由修改的解析器。1.1 现有开源方案为什么不够用我列一下实际对比过的主流方案方便你理解我当时的选型逻辑。cmarkC 库性能强悍但要在 Swift 里包一层桥接处理内存管理很麻烦。如果你只需要把 Markdown 转 HTML它很合适可如果你想在渲染前对 AST 做自定义操作桥接层会变成巨大的成本。Appleswift-markdown官方出品解析质量高但是库体偏大API 抽象程度高很多内部类型不开放。我试过用它做一套自定义的“引用块折叠样式”需要绕开不少封装越写越像在逆向。Down本质是 cmark 的 Swift 封装API 友好但底层依然是 C 解析器。我需要的是一个“任意节点都能替换渲染方式”的灵活度Down 做不到这种粒度。我真正需要的场景是这样的从服务端拿到的内容里有类似 [note]的标注我希望把这种引用块在客户端解析成一个自定义的“提示卡片”而不是普通 blockquote。如果用通用解析器就得先解析完 AST再遍历节点做二次转换既麻烦又容易漏。与其打补丁不如让解析器本身开放节点定义。1.2 MarkdownKit 的设计目标与取舍所以我把设计和取舍定成了几条硬约束。第一纯 Swift 实现。不桥接 C不依赖系统私有框架编译之后就是一个干净的 Swift Package。调试时能单步走进每一行解析逻辑对排查问题极其重要。第二解析结果要有“中间表示”。不是直接输出 HTML 或 NSAttributedString而是先产出一棵轻量节点树。树上的每个节点都是公开的 enum 或 struct上层可以自由遍历、增删、替换。第三语法支持做减法。我只实现了块级元素标题、段落、引用、列表、代码块、分割线和行内元素强调、加粗、链接、行内代码、图片GFM 里的表格、删除线、任务列表都不放在核心代码里。因为做减法之后解析器才能保持“一眼能看完”的体量用户也能在现有基础上自己扩展支持 GFM 子集。这种设计最直接的好处是你不需要懂编译原理只要理解“按行分块、块内扫行内”的状态机就能修改逻辑。接下来我详细拆一下解析流程。2. 解析器核心架构一个能看懂的状态机Markdown 解析本身不复杂难点在于处理嵌套和歧义。我的做法是把解析拆成两个阶段先做块级解析再做行内解析。块级解析负责把一大堆文本按空行和缩进切成有层级关系的块行内解析则负责在块内部扫出*强调*、[链接](url)、代码这些片段。2.1 块级解析把文本切成带语义的积木块级解析器是最核心的部分。我维护了一个栈结构BlockStack栈里的每个元素代表当前正在处理的块上下文。每次读取一行文本先判断这一行应该归属于哪个块类型。判断顺序很关键我写了个优先级缩进达到 4 个空格进入代码块行首是#且后面有空格生成 heading行首是-、*、且后面有空格生成 bullet list item行首是数字加点1.生成 ordered list item行首是生成 blockquote连续三个以上-、*、_生成 thematic break否则作为普通段落文本追加到当前段落块。这样的顺序能避开不少歧义。比如- foo既可以看成列表也可以看成段落里的连字符但因为列表判断在段落之前所以行为就明确。#这个符号因为要求“后面必须跟随空格或行尾”所以#hash#这种变量名不会被误判成标题。嵌套是通过栈来处理的。遇到引用时我不会直接创建孤立的引用块而是在栈上找最近的块级上下文把新块挂到它的 children 下。这样写出来的节点树引用、列表、段落之间的父子关系都很自然。块级解析完成后我会把所有块节点按顺序拼接成 AST。此时行内元素还停留在原始字符串状态全部交给第二遍处理。我当时花了不少时间处理一个细节空行在块解析中到底意味着什么。在 CommonMark 里空行通常会结束当前段落但在列表项内的空行不一定结束整个列表。我采用了一个相对简单的策略空行先丢弃但会设置一个“段落可结束”标记。如果下一行来了一个明显的新块起始标记就把当前段落封口如果下一行还是普通文本就继续追加。这个策略牺牲了一部分极端文档的准确性但换来了代码的简洁和可预测性。2.2 行内解析处理加粗、链接和代码行内解析是在块级 AST 确定之后对每个文本类型的叶子节点执行的。这里我没有用大正则一次性匹配所有语法理由是 Markdown 行内语法有转义和嵌套一个大正则会变成灾难。我改用“字符扫描 小状态机”的方式。具体做法是把文本切成字符数组用一个cursor索引从头往后扫。遇到\时如果下一个字符是 Markdown 符号就转义并作为普通字符输出遇到*时进入强调候选状态继续往后数连续星号个数匹配成对的闭合星号后递归调用行内解析处理中间的内容。链接的解析稍微复杂一点遇到[时先找到匹配的]再看后面是否紧跟(如果是就提取括号内的 URL 和可选 title。public struct InlineParser { public func parse(_ text: String) - [InlineNode] { var nodes: [InlineNode] [] var cursor text.startIndex while cursor text.endIndex { let char text[cursor] if char * { if let result parseEmphasis(text, cursor: cursor) { nodes.append(result) } } else if char [ { if let result parseLink(text, cursor: cursor) { nodes.append(result) } } else { // 收集普通文本直到遇到下一个特殊字符 let start cursor while cursor text.endIndex !isSpecial(text[cursor]) { cursor text.index(after: cursor) } nodes.append(.text(String(text[start..cursor]))) } } return nodes } }这里有一个值得注意的取舍行内解析器会递归地处理强调里的强调比如**foo *bar* baz**。递归深度一般不会超过 10 层性能没问题。但如果遇到极端嵌套比如*********************我会提前设置最大深度超过就不再解析直接作为普通文本输出。2.3 节点树、渲染协议与可自定义扩展点解析器输出的是节点树节点我定义为public enum BlockNode { case document([BlockNode]) case heading(level: Int, children: [BlockNode]) case paragraph([InlineNode]) case blockquote([BlockNode]) case list(isOrdered: Bool, items: [BlockNode]) case codeBlock(language: String?, text: String) case thematicBreak }所有渲染器都基于这棵树工作。我对外只暴露一个协议public protocol MarkdownRenderer { func renderDocument(_ children: [BlockNode]) - String func renderHeading(level: Int, content: String) - String func renderParagraph(_ content: String) - String func renderBlockquote(_ content: String) - String // ... }默认提供一个HTMLRenderer和AttributedStringRenderer。如果我想在某个界面里把引用块渲染成卡片样式只需要重写renderBlockquote方法在里面加上不同背景色或边框。这种协议设计背后隐藏着一个理念解析和渲染彻底分离。解析器只关心“这段话是什么结构”渲染器才关心“这段结构怎么显示”。我在实际项目中经常替换渲染器但解析逻辑几乎没动过。3. 五分钟集成自定义一个自己的渲染样式讲完架构说说怎么接入和改造。这部分我给的都是可以直接抄的代码你可以照着自己的需求调整。3.1 通过 Swift Package Manager 集成先在你的Package.swift里加依赖dependencies: [ .package(url: https://github.com/yourname/MarkdownKit.git, from: 1.0.0) ]然后在 target 里引入.target( name: YourApp, dependencies: [MarkdownKit] )如果你用 Xcode 工程直接在 File Add Package Dependencies 里粘贴仓库地址即可。这个包不依赖任何第三方库编译时间很短我第一次集成时最明显的感觉就是干净。解析入口很简单let parser MarkdownParser() let document parser.parse(markdownString) let html HTMLRenderer().render(document)这里生成的document就是前面说的节点树。你可以先打印出树的结构确认解析是否符合预期。我自己会写一个调试方法把节点树用缩进输出成纯文本排查问题特别直观。3.2 实现自定义 AST 节点与渲染器默认解析器不认识 [note]这种带标记的引用块。我实现自定义节点的思路分两步在解析阶段拿到 blockquote 时先检查其内部首段文本是否为[note]如果是就替换成一个.custom(String, [BlockNode])节点在渲染阶段对这个自定义节点输出“提示卡片”样式的 HTML。extension BlockNode { var isNoteBlock: Bool { if case .blockquote(let children) self, let first children.first, case .paragraph(let inlines) first, case .text(let text) inlines.first, text.hasPrefix([note]) { return true } return false } } final class NoteRenderer: HTMLRenderer { override func renderBlockquote(_ content: String) - String { // 这里根据节点判断决定是否渲染为自定义样式 return div class\note\\(content)/div } }这个思路简单有效。你甚至可以把这个能力做成协议扩展让每个业务模块都能往解析器里注入自己的“段落识别规则”。3.3 在 SwiftUI 里显示解析结果SwiftUI 里最直接的方式是把 HTML 转成AttributedString但这样会丢失很多自定义样式。我更推荐用AttributedStringRenderer它会把节点树映射成原生属性字符串。let renderer AttributedStringRenderer(configuration: .default) let attributed renderer.render(document) Text(attributed) .padding()如果你想完全掌控样式可以使用Text的init(_:style:)配合AttributedString的Markdown解析但这种方式只能处理少量语法。对于需要高度定制的业务界面我还是建议直接遍历节点树自己拼接 SwiftUI 视图。比如遇到.heading节点就生成不同字体大小的Text遇到.list节点就生成VStack。这样页面的交互能力完全不受限制。4. 实操中的坑嵌套、转义与性能调优解析器看起来简单真正写到生产环境会发现一堆边界情况。我把自己踩过的坑整理成了几个类别。4.1 正则回溯陷阱与转义处理最开始我用正则解析行内元素看起来代码很简洁static let emphasisRegex try! NSRegularExpression(pattern: \\*{1,2}([^*])\\*{1,2})但很快发现两个问题。第一个是回溯导致的性能抖动一篇几千字的文章在某些特殊字符组合下解析耗时可能超过一秒。第二个是转义问题用户输入的\*会被正则错误匹配因为正则并不理解反斜杠的含义。最后我彻底放弃了正则方案改成字符扫描虽然代码量增加了但每个字符最多只被访问两三次性能反而更稳定。处理转义时要注意顺序先处理反斜杠转义再处理其他语法。否则\*\*foo\*\*会被解析成强调而不是普通文本。我的扫描器在遇到\时直接吞掉下一个字符并标记为“已经跳过解析”这样后续逻辑就不会再对它做任何语法判断了。4.2 常见问题速查表与避坑心得这里放一个我自己整理过的问题表都是实际动过手才确认的经验。问题现象可能原因解决方式代码块里的*被解析成强调没有优先处理代码块标记确保块级解析先识别缩进或反引号代码块内的行不做行内解析列表后面的普通段落被错误塞进列表项块级状态机没有正确退出 list 上下文遇到连续两个空行且新行没有列表标记时强制弹栈回 document链接括号内含中文字符或空格时解析失败URL 提取逻辑没处理括号配对扫描时维护括号深度遇到(深度加一遇到)减少归零才算结束高亮高负载文本时 CPU 飙高行内解析对超大段落递归过深限制单个段落长度超过 8000 字符直接分成普通文本段渲染 HTML 时出现 XSS 风险没有转义原始文本当节点类型是.text时输出前调用 HTML 转义函数这类问题有一个共同点都是因为解析器“提前猜测了用户的意图”。如果你也希望解析器行为可预期最好的办法就是严格遵循“先识别结构再识别文本”的顺序不要试图在一遍扫描里完成所有判断。性能方面我的实测数据是一篇 300 行左右的 Markdown 文档解析加渲染耗时在 10 毫秒级。这个指标在普通 App 里完全够用但如果你的文档有几十万字建议把解析放到后台线程并且加上缓存。我在项目里就是用 MD5 对原始字符串做缓存键解析结果缓存起来滚动浏览时基本没有重复计算的负担。5. 能做什么、不适合做什么以及后续方向写到这里聊聊我对 MarkdownKit 边界的一些认识。它最适合的场景是内容以段落、列表、引用、代码块为主渲染层需要深度定制的客户端。比如资讯 App 的富文本详情、内部工具的工单说明、聊天消息里的代码片段高亮预览这些场景用这个解析器都很舒服。5.1 选型建议与适用场景如果你的文本来自用户输入且用户大概率会用到表格、删除线、任务列表这种 GFM 扩展语法那么 MarkdownKit 默认状态就不够用。但我建议别急着换库直接在解析器外面加一层“预处理”把 GFM 的表格语法先转成自定义节点或者扩展块级解析器里的判断分支新增一种.table节点成本远低于换掉整个解析核心。另外还有一个容易被忽视的点解析器不应该捆绑渲染器。我看过一些库把 CSS 样式和解析逻辑耦合在一起导致复用困难。MarkdownKit 从一开始就把渲染器做成协议所以同一棵树可以既输出 HTML也输出纯文本摘要。比如我做搜索功能时直接遍历节点树把所有.text节点拼接成纯文本不需要额外解析非常方便。5.2 如果让我重写一次我会改什么回头看这个项目最值得改进的是错误恢复机制。当前解析器遇到无法识别的行时会当作普通段落这在大多数情况下没问题但如果用户漏写了一个闭合符号可能会把后续大量内容吞进同一个引用块。如果让我重写我会在解析器里加入“块级约束检查”比如引用块嵌套层数超过 6 层时强制截断避免极端输入导致 UI 层级异常。另外行内解析的 API 也可以做得更友好。现在用户想自定义一个类似高亮的语法需要自己写扫描逻辑虽然扩展点是开放的但是门槛偏高。理想状态是提供一个“语法注册表”用户只需要声明起始标记、结束标记和渲染回调就能插入新语法。这个功能我放在后续的 Roadmap 里。我自己的体会是不要把 Markdown 解析器想成一个“黑盒工具”而应该把它当成一块可以自由雕刻的积木。解析器的价值不只是把 Markdown 变成可见的富文本更重要的是让你能读懂内容的结构并且有机会在结构之上做自己想要的加工。这个思维转换比任何具体代码实现都更值得投入。本文还有配套的精品资源点击获取