markdown-it-vue 踩坑排障：从安装到渲染的 6 个高频问题快速讲清

markdown-it-vue 踩坑排障：从安装到渲染的 6 个高频问题快速讲清

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

这篇文章写给刚装上 markdown-it-vue 就遇到报错的你，按"安装 → 启动 → 渲染"的顺序，把高频踩坑点与排障方法一次讲清。markdown-it-vue 是用 Vue 封装 markdown-it 的组件，开箱支持 GFM TOC、emoji、mermaid、echarts 和公式渲染。

📦 安装依赖阶段

安装报错：Vue 版本冲突怎么解

现象识别：npm install 中途失败，日志里出现 ERESOLVE 依赖冲突。

背后原因：这个库基于 Vue 2 生态，版本解析会和项目里的 Vue 3 打架。

解决操作：

1. 确认你项目的 Vue 版本，如果是 3.x，换用支持 Vue 3 的渲染组件。
2. 必须用它的话，锁定兼容版本安装：

npm install vue@2.6.14 markdown-it-vue

3. 仍失败就执行 npm cache clean --force 清理缓存后重装。

包体暴涨：换精简版

现象识别：打包产物比预期大出好几 MB，里面还带着 mermaid 和 echarts。

背后原因：完整版默认内置三个图表引擎，还顺带引了 lodash。

解决操作：

1. 不用图表功能就切到精简版：

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

2. 重新构建，确认产物体积明显变小。

🚀 首次启动阶段

页面裸奔无样式：漏引 css

现象识别：Markdown 出来了，但就是一坨没样式的纯文本。

背后原因：组件不会自动注入样式，css 需要你自己导入。

解决操作：

1. 在使用组件的入口文件加一行：

import 'markdown-it-vue/dist/markdown-it-vue.css'

2. 保存后刷新页面，样式就回来了。

Demo 端口被占用怎么改

现象识别：本地跑示例时，日志提示 8080 端口已被占用。

背后原因：别的本地服务占着默认端口。

解决操作：

1. 先查占用者：lsof -i :8080，确认无用就结束该进程。
2. 或者直接换个端口启动：

npm run dev -- --port 8081

📝 内容渲染阶段

echarts complains：图表渲染失败

现象识别：图表位置显示一行 echarts complains: ...，而不是图。

背后原因：组件会对图表代码块做 JSON 解析，JSON 非法就直接抛错。

解决操作：

1. 复制图表代码块内容，丢进 JSON 校验工具检查。
2. 补上缺失的引号、去掉多余逗号，保存后让它重新渲染。

公式变红、mermaid 不渲染：改 options

现象识别：公式显示为红色，或 mermaid 代码块只是纯文本。

背后原因：katex 解析失败会按 errorColor 标红；mermaid 语法错误则直接不画。

解决操作：

1. 通过 options 放宽公式容错：

options: { katex: { throwOnError: false, errorColor: '#cc0000' } }

2. 打开 mermaid 代码块逐行核对，修正语法错误。

✅ 预防清单

• 装之前先看 Vue 版本：本库只适配 Vue 2
• 不用 mermaid/图表就直接上精简版
• 导入组件时顺手导入 css 文件
• 图表代码块先过一遍 JSON 校验再粘贴
• 记录自己常用的 Demo 端口，避免冲突

更多插件默认配置见 README_CN.md，内置插件实现可参考 src/ 源码；遇到别的报错，直接去项目 issues 里搜关键词或提一个 issue 讨论。

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