做技术写作这几年我电脑里的.md文件多到数不清。真正让我难受的从来不是“写”而是“看”有时候只是想快速打开一个 Markdown 文档确认渲染效果检查代码高亮有没有问题既不想启动动不动几百 MB 的编辑器也不想把本地笔记粘贴到在线站点上——数据是自己的不想到处乱传。于是我用纯前端方式做了个基于浏览器的 Markdown 预览工具打开一个 HTML 文件通过文件导入方式载入.md文档浏览器本地完成 Markdown 解析和代码高亮渲染不依赖网络、不安装程序双击就能用。这个工具不试图成为编辑器只专注“预览”这一个动作。适合谁适合高频处理 README、技术笔记、接口文档的人适合电脑配置不高但天天要开一堆文件的人也适合那些只想让 Markdown 以最舒服的姿势显示出来的轻度用户。下面把整套思路、实现细节和踩过的坑都拆开讲你照着做也能在半小时内拥有一份属于你自己的轻量预览器。1. 项目定位为什么我还需要一个浏览器端的 Markdown 预览工具1.1 解决的核心痛点快速预览与轻量打开市面上的 Markdown 方案不少Typora 体验确实好但它是编辑器会给你一堆排版、主题、文件树的东西VS Code 也很强但为了看一个文件启动整个 IDE总觉得有点小题大做。更关键的是我经常要把文档发给没有装任何编辑器的人看对方只需要“打开一个文件把.md拖进去就能看到内容”不需要理解什么叫 Markdown 语法也不需要装环境。这个工具的核心定位就一句话打开浏览器把文件拖进去立刻看到渲染结果。它只在本地运行不上传任何内容关闭页面就什么都没了。对隐私敏感的场景来说这是一个很实在的加分项。它还可以配合打印功能做 PDF 导出算是一个“临时文档查看器”。1.2 技术选型对比marked、markdown-it 与 highlight.js、Prism 怎么选做浏览器端 Markdown 渲染第一关就是选解析库。我最早考虑的候选有三个marked、markdown-it、remark。简单说下区别解析库体积特点适合场景marked约 40KB老牌、默认支持 GFM、配置简单、解析速度快轻量工具、追求极简markdown-it约 100KB插件生态丰富、可高度定制需要扩展语法、复杂渲染remark更大Node 生态更完整浏览器端引入成本较高需要做 AST 级处理我做这个工具的原则是“轻量”所以选了 marked。它默认就支持 GFMGitHub Flavored Markdown表格、任务列表、删除线这些日常高频语法开箱即用不需要额外写插件。如果你以后想扩展自定义容器、脚注这些高级语法再考虑 markdown-it 也不迟但那是另一个项目了。代码高亮的选择更直接highlight.js 和 Prism.js 二选一。highlight.js 的好处是开箱即用一个 bundle 里带了上百种语言直接引入全量版本基本不会漏语言Prism 则需要手动挑选语言组件定制性强但第一次上手要折腾。我这种“能少配置就少配置”的诉求直接用 highlight.js 更省心。实际用下来 highlight.js 全量版不到 400KB对于本地工具来说可以接受换来的是省心。1.3 文件导入的三种实现路径FileReader、拖拽与粘贴用户要预览一个.md文件至少有三条路可以走通过input typefile选择文件这是最稳妥的保底方案任何浏览器都支持。把文件直接拖进浏览器窗口体验最好其实也只是监听drop事件一次preventDefault就能接住文件。从剪贴板粘贴 Markdown 文本适合电商运营、公众号小编这类“从聊天窗口复制一段带格式文本”的场景。三条路最终都汇聚到同一个入口拿到一段 Markdown 字符串交给解析库去渲染。我在工具里把前两种都做了第三种只留了一个文本框方便直接粘贴文本内容。这里有个容易被忽略的点拖拽文件时浏览器默认会在新标签页打开这个文件必须给dragover和drop都加上preventDefault()否则你辛辛苦苦拖进去的文件会变成浏览器直接显示源码等于白做了。2. 核心功能拆解与关键代码实现2.1 页面布局左右分栏、工具栏与移动端适配布局我用了最朴素的两栏结构左边是一个textarea放原始 Markdown 源码右边是一个div放渲染后的 HTML。上面一条细工具栏放导入按钮、打印按钮和一个状态提示。别看结构简单细节都在 CSS 里。两栏之间我用 flex 弹性布局左栏右栏各占一半中间加一条 1 像素的分隔线。窄屏时自动切成上下结构textarea在上、预览在下各自高度不少于 40vh。这里我特别处理了一个细节textarea使用等宽字体、关闭拼写检查、关闭自动换行避免源文件内容在编辑器里被折得乱七八糟渲染端则用正常比例字体。工具栏不要做得太重一个纯色条 几个按钮就够了。我在打印时把工具栏和源码输入区全部隐藏只保留渲染后的内容配合media print样式可以直接通过浏览器“打印为 PDF”输出干净的文档。2.2 文件读取input 事件、FileReader 与编码处理文件读取这块的核心 API 是FileReader.readAsText()代码并不复杂但容易踩坑的是编码。现在绝大多数.md文件都是 UTF-8readAsText默认按 UTF-8 解析没问题。如果碰到从旧 Windows 系统传过来的 GBK 编码文件读出来就是一堆乱码。document.getElementById(openBtn).addEventListener(click, function () { document.getElementById(fileInput).click(); }); document.getElementById(fileInput).addEventListener(change, function (e) { const file e.target.files[0]; if (!file) { return; } const reader new FileReader(); reader.onload function (ev) { document.getElementById(source).value ev.target.result; render(); }; reader.readAsText(file); });考虑到这是一个轻量工具我不想引入 jschardet 这种字符集检测库所以方案是默认按 UTF-8 读如果检测到替换字符\uFFFD或内容里出现大量乱码特征就在状态栏提示“文件可能不是 UTF-8 编码”。实际使用中遇到 GBK 文件的概率真的很低而且我后来把常用文件都转成 UTF-8 了这不算什么问题。拖拽导入的核心代码差别不大只是文件来源不同document.addEventListener(dragover, function (e) { e.preventDefault(); }); document.addEventListener(drop, function (e) { e.preventDefault(); const file e.dataTransfer.files e.dataTransfer.files[0]; if (!file) { return; } const reader new FileReader(); reader.onload function (ev) { document.getElementById(source).value ev.target.result; render(); }; reader.readAsText(file); });有一点要特别注意drop事件获取到的文件虽然能读取内容但浏览器出于安全考虑不会返回这个文件的完整路径。这意味着预览器在处理“相对路径图片”时会遇到麻烦这点我后面单独讲。2.3 Markdown 解析marked 配置、GFM 扩展与 XSS 安全过滤marked 的解析调用本身只有一行marked.parse(text)真正值得花心思的是配置。为了贴合大多数人的写作习惯我开了两个关键选项gfm: true和breaks: true。前者让表格、任务列表、自动链接生效后者把单个换行也渲染成br毕竟很多人在聊天软件和文档工具里被培养出的习惯是“回车就是想换行”不开 breaks 会让人觉得渲染结果和源码对不上。安全过滤是我强烈建议做的否则这个工具就是个大坑。如果直接把marked.parse(text)的结果塞进innerHTML而用户拖入的文档里包含恶意构造的 HTML比如img srcx onerroralert(1)或者一段script脚本就会在当前页面执行。文件是本地导入的可防不可防总归是个风险。我在渲染后加了一层DOMPurify.sanitize()白名单过滤这样只保留安全的标签和属性事件属性一律清除。function render() { const raw document.getElementById(source).value; const html marked.parse(raw); document.getElementById(preview).innerHTML DOMPurify.sanitize(html); }2.4 代码高亮marked 的 highlight 回调与 language 识别代码高亮的接入点选在 marked 的highlight回调里这里的关键是别把顺序搞反一定是“先解析 Markdown、再对代码块内容高亮”而不是“先高亮、再解析”。我见过很多新手先用 highlight.js 处理整段文本结果代码里的和被转义之后Markdown 解析器又对 HTML 标签做了处理最后页面显示全乱。marked.setOptions({ gfm: true, breaks: true, highlight: function (code, lang) { if (lang hljs.getLanguage(lang)) { try { return hljs.highlight(code, { language: lang }).value; } catch (e) { // 语言识别失败则回退到自动检测 } } return hljs.highlightAuto(code).value; } });如果代码块指定了语言就直接按这个语言高亮没指定语言才走highlightAuto。为什么不全部用自动检测因为自动检测在大段代码上比较慢而且偶尔会误判比如把 Python 识别成其他语言。显式语言是最准确的自动检测只是兜底。这里还藏了一个小坑python3这种语言名 highlight.js 并不识别很多人在代码块里写python3结果高亮失效而且不报错排查起来特别隐蔽。遇到这种情况可以在回调里对语言名做一次别名映射。2.5 预览体验优化滚动同步、防抖与打印导出静态预览做到这里已经能用了但体验上还差两件事滚动同步和打印导出。滚动同步的思路很直观左侧源码区域滚动的时候按滚动比例同步右侧预览区域。因为两栏内容高度不同不能直接按像素值相等来做要计算滚动百分比const sourceEl document.getElementById(source); const previewEl document.getElementById(preview); sourceEl.addEventListener(scroll, function () { const ratio sourceEl.scrollTop / (sourceEl.scrollHeight - sourceEl.clientHeight); previewEl.scrollTop ratio * (previewEl.scrollHeight - previewEl.clientHeight); });单向同步就够了不要做成双向同步否则很容易产生死循环抖动。至于输入防抖虽然现在是文件导入但导入后用户还是可能在文本框里改内容我加了 300ms 的防抖减少连续输入的重复渲染。打印导出的实现是给按钮绑一个window.print()配合前面提到的media print样式把工具栏和源码区隐藏只留渲染内容。这样浏览器自带的“打印为 PDF”功能就成了免费的导出器不需要额外做 PDF 生成库。如果你想生成独立的 HTML 文件再分享给别人可以用Bloba.download导出当前预览区的 HTML。3. 完整实操过程从零搭建一个可用的预览器3.1 目录结构单文件方案还是多文件方案先决定代码组织方式。我推荐一个文件搞定把 CSS 和 JavaScript 全部内联到index.html里。这样整个工具就是一个 HTML 文件拷到任何电脑、任何目录都能双击打开没有相对路径依赖。如果你喜欢维护性更好的方式也可以拆成index.html style.css app.js但注意本地通过file://协议打开时部分浏览器对 ES Module 方式加载有安全限制用普通script srcapp.js反而最省事。考虑到文章里讲的是轻量工具我直接以单文件为例。目录结构非常简单. ├── index.html ├── marked.min.js ├── highlight.min.js ├── highlight.github.min.css └── purify.min.js这里我特意没有用 CDN 链接原因很现实如果是本地工具一旦断网或者 CDN 域名被劫持整个工具就废了。把几个库下载到本地总大小也只有几百 KB换来的稳定性和隐私性非常划算。3.2 编写页面骨架与核心 CSS页面骨架是一个 header 工具栏加一个 main 两栏容器!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleMarkdown 预览工具/title link relstylesheet hrefhighlight.github.min.css style * { box-sizing: border-box; margin: 0; padding: 0; } body { font-family: -apple-system, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; } .toolbar { display: flex; gap: 8px; align-items: center; padding: 8px 16px; background: #f8f9fa; border-bottom: 1px solid #e9ecef; } .container { display: flex; height: calc(100vh - 56px); } #source { width: 50%; height: 100%; resize: none; border: none; padding: 16px; font-family: JetBrains Mono, Consolas, monospace; font-size: 14px; line-height: 1.6; outline: none; } #preview { width: 50%; height: 100%; overflow-y: auto; padding: 24px 32px; border-left: 1px solid #e9ecef; } media (max-width: 768px) { .container { flex-direction: column; } #source, #preview { width: 100%; height: 50%; } } media print { .toolbar, #source { display: none; } #preview { width: 100%; border: none; } } /style /head body div classtoolbar input typefile idfileInput accept.md,.markdown,.txt,text/markdown hidden button idopenBtn导入 .md 文件/button button idprintBtn打印 / 导出 PDF/button span idstatus stylecolor:#6c757d;font-size:13px;/span /div div classcontainer textarea idsource placeholder将 .md 文件拖入窗口或点击左上角导入按钮/textarea div idpreview classmarkdown-body/div /div script srcmarked.min.js/script script srchighlight.min.js/script script srcpurify.min.js/script script // ... 核心逻辑 /script /body /html同时给#preview补了一段 Markdown 专属样式主要处理标题层级间距、表格边框、代码块背景和行内代码底色。直接用全站统一样式会出问题比如段落间距太挤、表格没有边框、代码块里的字号和背景突兀。这套样式我建议固定下来不要省。3.3 核心 JavaScript导入、解析、渲染三件事串联下面把关键 JS 逻辑完整串起来。文件导入部分前面已经写过不再重复这里讲三个容易被忽略的细节。第一个细节是accept属性的写法。input的accept我写了.md,.markdown,.txt,text/markdown这样在文件选择窗口里会默认过滤出 Markdown 相关文件减少用户误选。但注意accept只是“建议”用户依然能切换到所有文件所以读取时要判断文件扩展名不符合的直接提示。第二个细节是“重复导入同一个文件”的场景。用户选中 A.md 预览完又选了 A.md由于input typefile的change事件只在值变化时触发连续选同一个文件可能不触发事件。解决办法是在读取结束后把fileInput.value置空或者每次用input.click()前重置。第三个细节是渲染失败的兜底。我用try...catch把marked.parse包裹起来万一某个异常构造的 Markdown 触发了解析器的 bug页面不至于白屏而是在状态栏显示“解析失败”并打印错误信息。这些细节乍一看不起眼实际用起来才是决定一个工具好不好用的关键。3.4 本地双击使用时的浏览器限制与应对直接双击index.html用file://协议打开绝大多数功能都是正常的但有几个限制你必须知道第一fetch本地文件会被大部分浏览器拦截。如果你试图用fetch去读同目录的某个文件Chrome 会直接报跨域错误。所以这个工具的敏捷之处就在于用FileReader读用户导入的文件绕开了这个限制。第二内联脚本和本地脚本都可以执行但 ES Module 的导入导出在file://下同样受 CORS 限制所以保持普通script标签是最安全的。第三CDN 资源在离线状态下不可用。这也是我建议把第三方库下载到本地的原因。如果你决定用 CDN 版本也要清楚这个工具会变得依赖网络和“轻量本地”的初衷就相悖了。4. 常见问题与排查技巧实录4.1 图片不显示真机预览和开发者工具表现不一致这个问题的典型现象是“我在开发者工具里看页面图片正常一到真机预览图片全挂了。”放在我们浏览器预览工具的场景里本质是同一件事——相对路径失效。Markdown 里常见的图片写法是。如果通过文件导入方式加载浏览器出于安全限制不会告诉我们原始文件的完整路径只知道文件内容。所以当你把.md拖进预览器时图片的./images/demo.png不知道该相对于谁解析——它不是相对于原始.md文件而是相对于当前index.html所在目录。我的解决思路是先给预览区统一设置一个“图片基础路径”甚至用一个输入框让用户指定图片前缀然后在渲染前对图片路径做一次正则替换把看看语言列表里有没有你需要的语言。没有就重新生成定制包或者直接换全量版。第三种渲染顺序错误。有些人先把整个 Markdown 文本丢给hljs.highlightAuto得到的结果再交给 marked 解析结果代码块本身的高亮逻辑被 marked 当成了普通文本处理。记住前面说的在 marked 的highlight回调里处理代码块而不是在render之前处理整个文本。4.3 换行与你想象的完全不同Markdown 语法里有个经典坑段落中间的单个换行默认不渲染成br。很多人写完发现渲染结果里句子全挤在一行还以为是自己代码写错了。这个问题的根源是 CommonMark 规范和大众直觉的冲突。为了兼容 GitLab、GitHub、Typora 等平台的常见行为我在 marked 配置里开了breaks: true。如果你用的是别的解析库可能叫linebreak或hardWrap配置名不同但目的一样。还有一个习惯建议如果确实要实现强制换行用两个空格加回车或直接空一行分段这是语法层面最稳妥的方式。4.4 大文件卡顿与内存占用优化有一次我拖了一个接近 1MB 的 Markdown 文件进去那个文件是把整本书的章节拼在一起渲染瞬间页面直接卡了两三秒。原因很简单marked 一次性把整个文档解析成 HTML 字符串浏览器一次性插入这么多 DOM 节点主线程当然扛不住。我的临时优化方案是在渲染函数外面包了一层 300ms 防抖配合requestIdleCallback把非关键渲染延后。更彻底的做法是把解析丢进 Web Worker但这样代码复杂度会上升对轻量工具来说有点过度设计。所以我给状态栏加了一个“文件较大渲染中……”的提示同时在代码里对大文件做了分批渲染的尝试先渲染前 2000 行再在下一个空闲间隔渲染剩余内容。实测 1MB 的文档从卡顿降到基本可接受。记住一点轻量工具的目标不是扛住所有极端场景而是给出一个合理的边界。4.5 常见问题速查表现象可能原因解决办法图片全部不显示相对路径基于当前 HTML 解析与原始 md 文件路径不一致设置图片基础路径或让 HTML 与 md 同目录文件打开全是乱码文件是 GBK 等非 UTF-8 编码另存为 UTF-8 后重新导入代码块没有高亮语言名错误、语言包缺失、处理顺序错误检查hljs.listLanguages()修正语言名表格显示成一堆竖线没有启用 GFM配置里开启gfm: true单换行不生效CommonMark 默认不渲染br开启breaks: true打印出来没有样式media print没有正确隐藏源码区检查打印样式隐藏.toolbar和#source大文件渲染卡顿DOM 节点过多防抖、分批渲染、提示等待5. 扩展建议这个预览器还能往哪些方向走5.1 公式渲染与目录大纲如果你经常用 Markdown 写技术文档大概率会用到数学公式。$x^2 y^2 z^2$这种行内公式在纯 marked 里无法识别会原样输出。一个低成本的增强方案是引入 KaTeX渲染前用正则识别$...$和$$...$$把公式部分替换成 KaTeX HTML。注意这个正则要写得足够克制避免把美元金额也误判成公式。目录大纲功能同样是高频需求。可以在渲染后扫描预览区里的h1到h6给每个标题插入带锚点的id再在页面左侧或顶部生成一个可点击的目录列表。技术上不复杂核心就是document.querySelectorAll(h1,h2,h3)加scrollIntoView()。这对动辄几千行的技术文档特别实用。5.2 与现有工作流结合导出 Word、PDF 与一键分享预览器虽然只负责“看”但“看”完之后的下一步通常是“发”。我自己的常规操作是内容确认没问题后直接window.print()导出 PDF发给同事或传到文档系统。如果你的工作流里要求最终输出 Word可以先把预览内容导出成完整 HTML再用 WPS 或 Word 打开另存为.docx。这里不展开具体转换工具的用法但思路和热搜词里的“markdown 转 word 工作流”是同一个方向。整个工具是纯静态的所以部署起来也极其便宜放到任意一个静态站点托管服务上或者直接内网共享其他人都能通过一个 URL 使用根本不用教他们怎么安装下载。5.3 从预览工具到笔记工作台最后分享一个我后来自己加的小功能把当前预览内容自动保存到localStorage。这样即使在浏览器里关了页面下次打开时上次的内容还在不会因为误关丢排版。再加上一个“复制为 Markdown”的按钮把渲染后的表格、引用内容反向复制成 Markdown 文本基本等于一个轻量笔记工作台了。我个人在实际操作中的体会是工具越轻就越难割舍。它不像大编辑器那样给你一堆面板和快捷键但你真正需要完整编辑器的时候往往是写长文或者做复杂排版不是只看一眼。如果你也受够了为了预览一个 Markdown 文件就启动几百 MB 的应用不妨按这个思路做一个属于自己的版本。整个过程不用什么高级技巧把文件读进来、解析、高亮三件事做好就已经解决了我日常八成的需求。