《周刊 No.08｜让 Markdown 编辑器承担恰当的责任》

栏目序号：第 8 期

导语：Markdown 编辑器看似简单，但在所见即所得（WYSIWYG）预览、原始文本保存、图片插入与 HTML 清理之间，常常存在责任不清、功能重叠或安全盲区。本期周刊聚焦于如何在设计与工程实践中为这些功能划定边界，给出可操作的判断与实现步骤，并指出常见误区，帮助工程师在复杂的产品约束中做出恰当选择。

核心判断：编辑器应该承担什么责任

任何编辑器的第一条原则是明确边界：哪些问题由编辑器负责解决，哪些问题应当留给后端或其它系统。编辑器的核心责任包括提供一致的用户体验、确保用户输入不会丢失以及在必要时进行初步的安全防护；而持久化策略、最终的内容过滤规则、图片存储与 CDN 管理、以及合规审查通常应该由后端或专门的服务承担。前端可以做轻量级的输入校验、实时反馈和体验优化，但不能替代服务器端的可信防护。这种分工既是一种安全实践，也是可维护性的要求。

所见即所得预览：表现而非决定

WYSIWYG 预览的作用是向用户展示渲染后的结果，但它不应承载对内容最终语义或安全策略的最终裁定。具体判断包括：预览可以在客户端渲染 Markdown、内联展示图片占位、实时高亮语法，但对是否允许某类 HTML 标签、是否保留特定属性、以及是否自动将外部资源转为代理，应当由后端配置的安全策略来决定。这样做的好处是客户端可以频繁迭代渲染体验，而后端安全策略更新不会被前端轻易绕开。

在实践上，WYSIWYG 预览要清晰地向用户显示当前编辑的“样子”，但应避免在视觉上隐含“这是最终结果”的错觉，例如不要在预览里展示未经授权的外部脚本、不要自动加载远程资源导致隐私泄露。预览渲染可以使用安全的渲染库或在沙箱环境中执行，但最终的过滤应落到服务器。

原始文本与存储策略：优先保留可编辑的原文

原始 Markdown 文本是作者意图的最直接表达，编辑器应始终保证原文的可恢复性。建议的做法是把原始文本作为第一类主数据进行存储，变换后的 HTML 或渲染产物作为派生数据缓存。这带来两个好处：一是当渲染规则改变（例如升级渲染引擎或调整插件行为）时，可以重新生成 HTML；二是在处理冲突或进行版本回滚时能够还原用户最初的输入。

此外，应当区分“编辑时的本地草稿”与“已发布的存档”。本地草稿可以包含未经清理的临时 HTML 片段或富文本中间状态，但发布流程必须经过后端清理和审核链路。对工程师来说，这意味着在 API 设计上要明确字段：raw_markdown、rendered_html（可缓存）、attachments（图片元数据）等，避免把渲染结果作为权威数据写死。

图片插入与资源管理：编辑器与后端的分工

图片插入常常是用户体验的核心场景，但也带来存储、性能与安全问题。编辑器应负责提供便捷的上传与拖放体验、生成本地预览（data URL 或临时 blob URL）、并将图片元信息提交到后端。后端负责持久化、去重、生成不同尺寸、刷 CDN、以及控制访问权限。关键的工程实践包括：前端上传时明确返回资源 ID、URL 模式使用后端生成的受控地址、并避免直接在前端拼接外部托管地址以防止链接注入或权限绕过。

图片插入时也要考虑隐私与成本，比如是否允许外部 URL 嵌入图片（hotlink）。如果允许，应在后端对外链进行代理或抓取并存储一份受控副本，而不是仅在编辑器中展示外链预览。这样能防止第三方追踪、避免外链失效后页面损坏，也便于统一审计。

用户界面可以并应当提供即时反馈，但任何涉及安全、访问控制与持久化的数据转换，都应在后端完成最终判定。

HTML 清理：谁来决定清理规则与策略

HTML 清理是整个链路中最容易被误用的部分，因为它既涉及安全（XSS、注入），也涉及可用性（允许哪类嵌套元素、样式）。原则是双层防护：前端可做轻量级白名单以提高编辑体验并减少明显的危险输入，后端必须执行严格且可配置的清理流程。后端清理策略要可审计、可回滚，并且与应用的最终安全要求一致。例如，有些内部应用可能允许特定的 style 属性或 data-* 属性；这类例外只能在后端且通过配置或策略管理，而不应由每个前端实例私自决定。

工程实现建议是采用成熟的库进行 HTML 清理，并在版本控制下维护清理规则集。清理流程应包含日志记录（记录被清理或拒绝的片段）、规则变更审查，以及在必要时提供逐条人工复核的通道。对外开放的平台还需要考虑分级策略：普通用户与受信任用户可以有不同的白名单级别，但白名单差异同样应由后端态势管理，而非前端差异化实现。

实践步骤与工程建议

1. 明确数据模型：保存原始 Markdown（raw），存储清理后的 HTML（html），图片作为独立资源对象（attachment）。API 设计应清晰区分这三者。
2. 将最终的安全与合规判定放在服务器端：后端责任包括 XSS 过滤、外部资源抓取、权限控制与持久化策略。前端承担体验和预校验。
3. 预览使用安全渲染（沙箱或纯渲染库），并在 UI 上提示“预览可能与最终发布存在差异”以避免误导用户。
4. 图片上传采用异步上传并返回资源 ID，插入操作只引用资源 ID 而非外链地址；如果允许外链必须由后端抓取并存储副本。
5. HTML 清理使用成熟库并将规则纳入版本控制和审计流程。对规则的任何宽松或严格调整都应通过变更管理，并同步到渲染测试套件。
6. 在多人协作场景下，合并与冲突解决策略应优先保留原始文本；由后端或合并服务来重建最终渲染版本，避免在客户端尝试做复杂的三方合并逻辑。

常见误区与如何避免

• 误区：把所有清理逻辑都放在前端，认为这样可以减少后端负担。后果是安全策略容易被绕过，且规则不一致。避免方法：前端做体验级检查，后端做最终过滤。
• 误区：将渲染结果作为主数据存储，忽视原始文本的重要性。后果是渲染规则更新时无法回滚。避免方法：始终保留原文并将渲染产物视为缓存。
• 误区：允许未经审查的外链图片直接渲染，认为方便即可。后果是隐私泄露和页面不可控。避免方法：后端抓取并提供受控 URL，或对外链进行代理。
• 误区：以用户体验为由放宽 HTML 白名单，忽略审计与版本控制。避免方法：所有白名单修改要有变更记录、测试套件和回退路径。

结语

设计一个健壮的 Markdown 编辑器并非仅仅是前端组件的工程，关键在于明确职责边界、建立可审计的后端清理与资源管理流程、并把“用户体验”和“系统可信赖性”放在同等重要的位置。工程实践要求团队在早期就达成这些共识，并在产品发展过程中持续对渲染规则、存储模型与安全策略进行治理。

延伸阅读

• Flask Documentation: https://flask.palletsprojects.com/en/stable/
• MDN Web Docs: https://developer.mozilla.org/