markdown-it-vue 避坑速查：从安装到 Markdown 渲染一次跑通

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

markdown-it-vue 是一个 Vue 2 的 Markdown 渲染组件，用 markdown-it 做解析引擎，把 GFM 目录、emoji、mermaid 图表、Echarts、KaTeX 公式这些渲染插件全打包好了。这篇写给刚 clone 下来就跑 demo、被依赖版本冲突和渲染异常卡住的同事，照着排一遍基本能一次跑通。

📦 项目速览

• 主语言 JavaScript，框架 Vue 2，别指望直接挪去 Vue 3 用
• 核心依赖一次装齐：markdown-it 12、highlight.js 代码高亮、mermaid、echarts、KaTeX 公式
• 内置能力：GFM 目录、emoji、任务列表、脚注、上下标、图片查看器，外加 mermaid、Echarts、flowchart 图表
• 包体积敏感就换 markdown-it-vue-light，代价是砍掉 mermaid
• 本地跑 demo 先把仓库拉下来：

git clone https://gitcode.com/gh_mirrors/ma/markdown-it-vue

⚠️ 上手最容易踩的 3 个坑

装完依赖直接报错？多半是版本打架

项目锁的是 markdown-it 12，你要是主项目里别处装了 13 系，npm install 大概率直接 ERESOLVE 怼你一脸。

npm cache clean --force
npm install markdown-it@12 markdown-it-vue

跑完如果还报错，把依赖里所有用到 markdown-it 的包列一遍，版本统一掉再装。

Demo 起不来：端口被谁偷走了

yarn dev 默认往 8080 上跑，本机已有服务占着的话，要么报错要么静默起不来。

→ 先查占用：lsof -i :8080 找到对应的 PID 直接干掉 → 再改端口：dev 脚本里加 --port 8081，省得每次手敲 → 重新 yarn dev，浏览器访问新端口确认页面

公式图表渲染出来是"一坨"

贴段 KaTeX 公式进去，页面要么一串串红字，要么整块白屏，多半不是公式本身写错了。

错误做法	正确做法
只注册组件，配套的 css 文件忘引	组件和 css 一起 import
插件选项随便塞进 data 里	统一放进 options 属性，按插件名分 key 透传

改完刷新还不对，把 options 里对应插件那段删掉、走默认配置试一次，默认值是作者调好的。

🔍 问题反复出现时的通用排查思路

• 渲染结果不对 → 先看浏览器控制台有没有插件报错 → 再对照默认 options 查配置层级
• 装依赖反复失败 → 先看 lock 文件里 markdown-it 解析出的版本 → 再清缓存统一版本重装
• 改了代码没生效 → 先看 dev server 热更新有没有成功 → 再硬刷新浏览器清缓存
• 某个图表不显示 → 先看是不是 light 版本把 mermaid 砍了 → 再确认对应图表库引没引

版本、端口、配置三件事理顺之后，demo 应该能独立跑起来，剩下的就是照着 README 往 options 里填你自己的配置了。

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