mp-html是uni-app三端统一渲染Markdown最稳妥方案,通过解析HTML为原生组件树实现表格、代码块等完整支持,避免v-html在小程序中的白屏与乱码问题。

mp-html 是当前 uni-app 项目中渲染 Markdown 最稳妥、开箱即用的选择,尤其适合 H5 + 微信小程序 + App 三端统一场景。它不是“把 Markdown 转成 HTML 再 v-html”,而是把 HTML 字符串解析为原生组件树(rich-text + 自定义节点),能真正渲染表格、代码块、标题层级等——而直接用 v-html 在小程序里基本是白屏或乱码。
使用 SQLite FTS5 对结构化 Markdown 文档库进行全文搜索,适用于需要快速、高效搜索大量 Markdown 文章的场景。
为什么不能直接用 marked + v-html?
小程序的 rich-text 组件对 HTML 标签支持极弱:<table>、<code><pre class="brush:php;toolbar:false;"></code>、<code><code></code>、带 <code>class</code> 的标签全被过滤;<code>v-html</code> 在非 H5 端根本不可用。你看到的“乱码”其实是未被识别的原始符号(比如 <code>### 标题</code> 直接显示为文字)。更关键的是,<code>v-html</code> 无法触发点击复制代码、图片预览、TOC 跳转等交互。</p><h3>mp-html 安装与基础用法(Vue 3 项目)</h3><p>安装命令必须用 Vue 3 兼容版:</p><pre class="brush:php;toolbar:false;">npm install mp-html@latest</pre><p>在页面中直接使用(无需全局注册):</p><pre class="brush:php;toolbar:false;"><template>
<mp-html :content="htmlContent" />
</template>
<p><script setup>
import { ref, onMounted } from 'vue'
import { marked } from 'marked'
import hljs from 'highlight.js/lib/common'
import 'highlight.js/styles/github.css'</p><p>const htmlContent = ref('')</p><p>onMounted(() => {
const md = '# Hello\n\n<code>js\nconsole.log("uni-app")\n</code>'
const html = marked(md, {
highlight: (code, lang) => {
try {
return hljs.highlight(code, { language: lang }).value
} catch {
return hljs.highlightAuto(code).value
}
}
})
htmlContent.value = html
})
</script></pre><ul>
<li>
<code>mp-html 只接收已转好的 HTML 字符串,不内置 Markdown 解析器,所以得自己用 marked 或 markdown-it 预处理
highlight.js 并传给 marked,否则代码块只是纯文本mp-html 默认禁用内联样式,如需自定义颜色/字体,得通过 styles prop 或全局 CSS 类覆盖towxml 适合什么场景?
当你需要数学公式(LaTeX)、流程图(Mermaid)、自动生成目录(TOC)、或重度技术文档时,towxml 更合适。但它有硬性约束:
- 必须放在
wxcomponents/towxml目录下,路径写错就加载失败 - 要在
pages.json的usingComponents中显式声明,且只对当前页面生效 - 初始化必须在
main.js(Vue 2)或main.ts(Vue 3 SSR)里挂载到app.config.globalProperties,漏掉这步会报this.$towxml is not a function - 返回的是节点数组(
nodes),不是 HTML 字符串,要传给<towxml :nodes="xxx"></towxml>
容易踩的坑:图片和 base64 处理
从 GitHub API 或后端读取的 Markdown 常含相对路径图片或 base64 图片,mp-html 默认不处理这些:
- 相对路径图片(如
)会 404,需在marked渲染前用正则替换为绝对路径或 CDN 地址 - base64 图片(如
)在小程序里可能被拦截,得用uni.downloadFile临时保存再转本地路径,或改用mp-html的customNodehook 拦截img标签并重写src - 大图未做懒加载会卡顿,建议配合
mp-html的lazyLoad属性 +imageslot 自定义加载占位
最常被忽略的一点:无论选 mp-html 还是 towxml,都不要在 onLoad 里直接解析长 Markdown —— 同步解析 >10KB 文本会导致小程序主线程卡死。务必用 setTimeout 或 nextTick 延迟渲染,或分片处理。

















