Vue 2 安装

使用 pnpm、npm 或 yarn 安装 markstream-vue2。

pnpm add markstream-vue2
# 或
npm install markstream-vue2
# 或
yarn add markstream-vue2

要求

markstream-vue2 需要：

• Vue 2.6.14+（推荐使用 Vue 2.7 以获得更好的 TypeScript 支持）
• @vue/composition-api（如果使用 Vue 2.6.x）

可选的对等依赖

markstream-vue2 通过可选的对等依赖支持各种功能。只安装你需要的功能：

功能	所需包	安装命令
Shiki 代码块（MarkdownCodeBlockNode）	shiki、stream-markdown	pnpm add shiki stream-markdown
Monaco 编辑器（完整代码块功能）	stream-monaco	pnpm add stream-monaco
Mermaid 图表	mermaid	pnpm add mermaid
数学公式渲染（KaTeX）	katex	pnpm add katex

Vue 2.6.x 设置

如果你使用的是 Vue 2.6.x，需要安装并配置 @vue/composition-api：

pnpm add @vue/composition-api

然后在你的应用入口文件中：

import VueCompositionAPI from '@vue/composition-api'
import Vue from 'vue'

Vue.use(VueCompositionAPI)

功能加载器（Mermaid / KaTeX）

安装可选对等依赖后，默认 loader 已经启用。仅当你之前手动关闭，或需要自定义 loader（例如使用 CDN 版本）时才需要调用：

import { enableKatex, enableMermaid } from 'markstream-vue2'

// 可选：重新启用或覆盖 loader
enableMermaid()
enableKatex()

同时记得导入必需的 CSS（按需使用）：

import 'markstream-vue2/index.css'
import 'katex/dist/katex.min.css'

Monaco（stream-monaco）不需要单独导入 CSS。

注意：markstream-vue2/index.css 的样式被限制在内部的 .markstream-vue2 容器下，以减少全局样式冲突。MarkdownRender 默认在该容器内渲染。如果你单独渲染节点组件，请用 <div class="markstream-vue2">...</div> 包裹它们。

Vue CLI（Webpack 4）特别说明

Vue CLI 4 默认使用 Webpack 4，它不支持 package.json#exports，因此以下写法会在 Webpack 4 下解析失败：

• import 'markstream-vue2/index.css'
• import('mermaid')
• Vite 风格的 worker 导入：?worker / ?worker&inline

推荐做法（可直接参考 playground-vue2-cli）：

1. CSS 改用真实路径（不依赖 exports）：

import 'markstream-vue2/dist/index.css'

2. Mermaid 推荐使用 CDN 的全局构建（避免 Webpack 4 解析 exports / ESM 依赖链）：

<!-- public/index.html -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>

3. KaTeX / Mermaid worker 推荐使用 CDN worker（避免 Webpack 4 worker 限制）：

import { createKaTeXWorkerFromCDN, createMermaidWorkerFromCDN, setKaTeXWorker, setMermaidWorker } from 'markstream-vue2'

const { worker: katexWorker } = createKaTeXWorkerFromCDN({
  mode: 'classic',
  katexUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.js',
  mhchemUrl: 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/contrib/mhchem.min.js',
})
if (katexWorker)
  setKaTeXWorker(katexWorker)

const { worker: mermaidWorker } = createMermaidWorkerFromCDN({
  mode: 'classic',
  mermaidUrl: 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js',
})
if (mermaidWorker)
  setMermaidWorker(mermaidWorker)

如果你希望继续使用 markstream-vue2/index.css 这类导入路径，需要在 vue.config.js 里做 resolve.alias 映射（见 playground-vue2-cli/vue.config.js）。

代码块：推荐用 stream-markdown 覆盖

在 Webpack 4 下，Monaco 集成（stream-monaco）很容易踩到边角问题（worker 定位、ESM 入口、service 注册、以及 Shiki/TextMate regex engine 初始化等）。如果你的目标是“让代码块正确高亮渲染”，更稳妥的方案是：

1. 安装 Shiki 渲染依赖：

pnpm add shiki stream-markdown

2. 覆盖 code_block，直接使用 MarkdownCodeBlockNode（或你自己的组件）：

import { MarkdownCodeBlockNode, setCustomComponents } from 'markstream-vue2'

setCustomComponents({ code_block: MarkdownCodeBlockNode })

3. Webpack 配置踩坑：

• 如果你使用 webpack.IgnorePlugin 忽略可选依赖，确保不要把 stream-markdown 忽略掉。
• stream-markdown 是 ESM-only 包，在 CJS 的 vue.config.js 里即便已安装，require.resolve('stream-markdown') 也可能失败；建议用文件系统兜底定位 node_modules/stream-markdown 并 alias 到 dist/index.js。可参考 playground-vue2-cli/vue.config.js。

另外，如果你的项目是 monorepo/workspace（pnpm 常见），请确保整个应用只使用 同一份 Vue 2 runtime。否则会出现类似： provide() can only be used inside setup() / onMounted is called when there is no active component instance 的运行时警告（本质是重复 Vue 实例导致 Composition API 上下文不一致）。解决方式是在 Webpack 中固定 vue$ 指向项目内的 Vue 2 runtime（见 playground-vue2-cli/vue.config.js）。

Tailwind CSS 支持

如果你的项目使用 Tailwind，并希望避免重复注入 Tailwind utilities，请改用 Tailwind-ready 输出：

import 'markstream-vue2/index.tailwind.css'

并在 tailwind.config.js 的 content 中加入该包导出的 class 列表：

module.exports = {
  content: [
    './src/**/*.{js,ts,vue}',
    require('markstream-vue2/tailwind'),
  ],
}

这种方式可以确保 Tailwind 在清除未使用的样式时包含 markstream-vue2 使用的所有工具类，从而获得更小的最终打包体积。

快速安装：所有功能

一次性启用所有功能：

pnpm add shiki stream-markdown stream-monaco mermaid katex
# 或
npm install shiki stream-markdown stream-monaco mermaid katex

功能详情

代码语法高亮

需要同时安装 shiki 和 stream-markdown：

pnpm add shiki stream-markdown

这些包用于 Shiki 版的 MarkdownCodeBlockNode。若要在 MarkdownRender 中使用 Shiki，请覆盖 code_block 渲染器（或直接使用 MarkdownCodeBlockNode）。

import MarkdownRender, { MarkdownCodeBlockNode, setCustomComponents } from 'markstream-vue2'

setCustomComponents({ code_block: MarkdownCodeBlockNode })

Monaco 编辑器

完整的代码块功能（复制按钮、字体大小控制、展开/折叠）：

pnpm add stream-monaco

如果不安装 stream-monaco，代码块仍会渲染，但交互式按钮可能无法工作。

Mermaid 图表

渲染 Mermaid 图表：

pnpm add mermaid

KaTeX 数学公式渲染

数学公式渲染：

pnpm add katex

同时在应用入口文件中导入 KaTeX CSS：

import 'katex/dist/katex.min.css'

快速测试

导入并渲染一个简单的 markdown 字符串：

<script>
import MarkdownRender from 'markstream-vue2'
import 'markstream-vue2/index.css'

export default {
  components: {
    MarkdownRender
  },
  data() {
    return {
      md: '# Hello from markstream-vue2!'
    }
  }
}
</script>

<template>
  <MarkdownRender :content="md" />
</template>

使用 Composition API（Vue 2.7+）

如果你使用的是 Vue 2.7 或已安装 @vue/composition-api：

<script>
import { defineComponent, ref } from '@vue/composition-api' // 或 Vue 2.7 的 'vue'
import MarkdownRender from 'markstream-vue2'
import 'markstream-vue2/index.css'

export default defineComponent({
  components: {
    MarkdownRender
  },
  setup() {
    const md = ref('# Hello from markstream-vue2 with Composition API!')
    return { md }
  }
})
</script>

<template>
  <MarkdownRender :content="md" />
</template>

TypeScript 支持

markstream-vue2 包含 TypeScript 类型定义。对于 Vue 2.6.x，你可能需要配置 tsconfig.json：

{
  "compilerOptions": {
    "types": ["@vue/composition-api"]
  }
}

对于 Vue 2.7+，类型会自动包含。