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 和公式渲染。典型现象可能原因快速解法npm install 报 ERESOLVE 冲突依赖 Vue 2与 Vue 3 项目打架先确认 Vue 版本别在 Vue 3 硬装装完页面裸奔无样式没引入样式文件导入 markdown-it-vue.css页面出现 echarts complains图表代码块 JSON 非法校验并修正 JSONmermaid 图渲染不出来代码块语法错误逐行修正 mermaid 语法Demo 端口被占用8080 被别的进程占了换端口或结束进程再启动 安装依赖阶段安装报错Vue 版本冲突怎么解现象识别npm install 中途失败日志里出现 ERESOLVE 依赖冲突。背后原因这个库基于 Vue 2 生态版本解析会和项目里的 Vue 3 打架。解决操作确认你项目的 Vue 版本如果是 3.x换用支持 Vue 3 的渲染组件。必须用它的话锁定兼容版本安装npm install vue2.6.14 markdown-it-vue仍失败就执行 npm cache clean --force 清理缓存后重装。包体暴涨换精简版现象识别打包产物比预期大出好几 MB里面还带着 mermaid 和 echarts。背后原因完整版默认内置三个图表引擎还顺带引了 lodash。解决操作不用图表功能就切到精简版import MarkdownItVueLight from markdown-it-vue/dist/markdown-it-vue-light.umd.min.js重新构建确认产物体积明显变小。 首次启动阶段页面裸奔无样式漏引 css现象识别Markdown 出来了但就是一坨没样式的纯文本。背后原因组件不会自动注入样式css 需要你自己导入。解决操作在使用组件的入口文件加一行import markdown-it-vue/dist/markdown-it-vue.css保存后刷新页面样式就回来了。Demo 端口被占用怎么改现象识别本地跑示例时日志提示 8080 端口已被占用。背后原因别的本地服务占着默认端口。解决操作先查占用者lsof -i :8080确认无用就结束该进程。或者直接换个端口启动npm run dev -- --port 8081 内容渲染阶段echarts complains图表渲染失败现象识别图表位置显示一行 echarts complains: ...而不是图。背后原因组件会对图表代码块做 JSON 解析JSON 非法就直接抛错。解决操作复制图表代码块内容丢进 JSON 校验工具检查。补上缺失的引号、去掉多余逗号保存后让它重新渲染。公式变红、mermaid 不渲染改 options现象识别公式显示为红色或 mermaid 代码块只是纯文本。背后原因katex 解析失败会按 errorColor 标红mermaid 语法错误则直接不画。解决操作通过 options 放宽公式容错options: { katex: { throwOnError: false, errorColor: #cc0000 } }打开 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考