企业官网建设流程全解析

markdown-it-vue 新手避坑：8 个高频坑与一次跑通的排错路径

【免费下载链接】markdown-it-vueThe vue lib for markdown-it.项目地址: https://gitcode.com/gh_mirrors/ma/markdown-it-vue

markdown-it-vue 是一个基于 Vue 2 的 Markdown 渲染组件，以 markdown-it 为解析引擎，内置十几个插件，开箱支持目录、emoji、公式、mermaid 与 Echarts 图表。这篇文章按安装、启动、渲染排查、升级四个阶段，带你把新手最常卡住的环节逐个排干净。

项目速览

markdown-it-vue 做的事情很直接：把 Markdown 文本交给 markdown-it 解析，再把渲染结果通过 Vue 组件输出，省掉手写解析和逐个挂插件的流程。它内置了 emoji、下标/上标、脚注、删除线、任务列表、KaTeX/LaTeX 公式、Font Awesome 图标等能力，还自研了图片预览与尺寸控制、Echarts、mermaid、flowchart.js 渲染插件。项目用 JavaScript 编写，基于 Vue 2 和 vue-cli 4 构建，另外提供一个去掉 mermaid 的精简版 markdown-it-vue-light。所有插件行为都能通过组件的options属性下发，也支持用use方法追加自定义 markdown-it 插件。

安装与依赖准备：先把组件装对

Vue 版本是第一道坎

装完依赖、模板里也写了<markdown-it-vue>，页面却一片空白，控制台提示 Unknown custom element——这是新手遇到的第一个坑。原因不在安装本身：项目的依赖锁定在vue ^2.6.12，组件用 Options API 和$refs编写，没有适配 Vue 3。动手之前先确认宿主项目是 Vue 2；如果是 Vue 3 项目，不建议硬装，可以等社区兼容版本，或先用精简封装隔离。确认版本无误后再执行安装：

npm install markdown-it-vue

若 npm 在解析依赖时报版本冲突，用npm ls markdown-it看一下最终解析出的版本，是否与组件依赖的 12.x 一致，必要时锁定版本重装，而不是盲目升级。

文字出来了，样式全乱了

渲染结果没有 GitHub 风格、排版错乱，多半是漏了样式文件：github-markdown-css是通过 dist 产物里的 css 引入的，装组件不等于引样式。在入口文件补一行import 'markdown-it-vue/dist/markdown-it-vue.css'（精简版对应-light.css）即可恢复。

首次启动与环境

跑官方 Demo 报 OpenSSL 错误

clone 仓库（git clone https://gitcode.com/gh_mirrors/ma/markdown-it-vue）后执行npm run dev，新版 Node 用户会直接看到ERR_OSSL_EVP_UNSUPPORTED崩溃。原因是构建链是 vue-cli 4 / webpack 4，而 Node 17+ 的 OpenSSL 3 禁用了旧的 MD4 哈希算法。两条路都能走：临时设置NODE_OPTIONS=--openssl-legacy-provider再启动，或者把 Node 降到 14 / 16 LTS。

打包体积突然暴涨

产物从几百 KB 涨到 2MB 以上、构建还特别慢，元凶是 mermaid：完整版内嵌 mermaid 8.x，它把整个 lodash 拉了进来。如果业务用不到 mermaid，直接换精简版，两行引入即可：

import MarkdownItVueLight from 'markdown-it-vue/dist/markdown-it-vue-light.umd.min.js' import 'markdown-it-vue/dist/markdown-it-vue-light.css'

注意精简版中 mermaid 代码块不会渲染，选型前先确认功能边界。

渲染不生效？🔍 按特性逐个定位

HTML 被转义成一堆尖括号文本

Markdown 里夹的<div>、<br>以纯文本形式显示，原因是默认配置下 markdown-it 的html是关闭的（出于 XSS 安全考虑），组件默认只开了linkify。需要在 options 里显式打开：

:options="{ markdownIt: { html: true, linkify: true } }"

这里藏着一个容易忽略的细节：options对同一个字段是整体覆盖，不是深合并——只传html会丢掉默认的linkify，写配置时要把该字段需要的项一起带上。

页面出现 "echarts complains" 文本

Echarts 代码块没出图，反而渲染出一段 pre 包裹的错误文本；flowchart 同理会显示 "flowchart complains"。组件对这两类图表做了 try/catch，把解析失败的 JSON 或运行异常直接吐回了页面。判断方向有两个：一是 JSON 本身不合法（缺宽高、series 不完整），二是图表类型超出支持范围——完整版为了控制体积只打包了echarts.simple，K 线、地图等高级类型并不在其中。先在控制台看真实报错，再修 JSON 或换支持范围内的图表类型。

代码块没有高亮

某语言代码块显示为纯文本，是因为高亮基于 highlight.js，但为控制体积只打包了常用语言（js、py、go、rust、sql 等四十来种）。先核对语言名是否在支持列表里；冷门语言目前没有现成语言包，可以提 PR 补充，或自行替换高亮方案。

目录和图表"缺斤少两"

[toc]生成的目录只包含部分标题，是因为 TOC 默认只收 h2 和 h3（tocFirstLevel: 2、tocLastLevel: 3），一级标题不会进目录，需要通过options.githubToc调整层级。另一类情况是 mermaid 新语法画不出图：内置版本是 8.9.2，不支持后续大版本才引入的图类型，写图时把语法限制在 8.x 支持的范围内即可。

常见问题速查表

升级与迁移

动大依赖前先读插件源码

升级 mermaid、echarts 这类大版本前，先看项目里对应插件的写法：内置插件实现都在 src 目录下，如markdown-it-plugin-mermaid.js、markdown-it-plugin-echarts.js，它们直接调用了旧版本 API，只升依赖不改调用点大概率翻车。更稳妥的做法是小步升级、对照渲染结果回归一遍图表。

想加自定义插件

不需要改组件源码，拿到组件 ref 后调用use即可，例如this.$refs.myMd.use(MyPlugin)；渲染完成还会触发render-complete事件，适合在里面做后续处理。

完整插件清单、默认选项和支持的高亮语言见项目根目录的 README_CN.md，更细的选项字段定义在 types 目录的markdown-it-vue.d.ts中。解析层的疑难问题，建议对照 markdown-it 官方文档排查。

【免费下载链接】markdown-it-vueThe vue lib for markdown-it.项目地址: https://gitcode.com/gh_mirrors/ma/markdown-it-vue