Vue 2 安装

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

bash

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）

Composition API 版本兼容（Vue 2.6 / 2.7 / 3.x）

Vue 版本	Composition API 状态	需要安装	如何导入
2.6.x	不内置	`@vue/composition-api`	`import { ref, computed, defineComponent } from '@vue/composition-api'`
2.7.x	内置	无	`import { ref, computed, defineComponent } from 'vue'`
3.x	内置	无	`import { ref, computed, defineComponent } from 'vue'`

注意：

Vue 2.6.x 必须安装并 Vue.use(@vue/composition-api)，否则会出现运行时报错。
Vue 2.7.x 不需要 安装 @vue/composition-api（内置）。
Vue 3.x 请使用 markstream-vue（不是 markstream-vue2）。

按版本快速开始（依赖 + 入口）

Vue 2.6.x

依赖：

bash

pnpm add markstream-vue2 vue@2.6.14 vue-template-compiler@2.6.14 @vue/composition-api

入口文件：

import VueCompositionAPI from '@vue/composition-api'
import MarkdownRender, { VueRendererMarkdown } from 'markstream-vue2'
import Vue from 'vue'
import 'markstream-vue2/index.css'

Vue.use(VueCompositionAPI)
Vue.use(VueRendererMarkdown)

new Vue({
  render: h => h(MarkdownRender, { props: { content: '# Vue 2.6' } }),
}).$mount('#app')

在组件里使用 Composition API：

import { defineComponent, ref } from '@vue/composition-api'

仓库示例：

playground-vue2-cli（Vue 2.6 + Vue CLI / Webpack 4）

路径与启动命令：

bash

pnpm -C playground-vue2-cli dev

也可以在仓库根目录直接运行：

bash

pnpm play:vue2-cli

Vue 2.7.x

依赖：

bash

pnpm add markstream-vue2 vue@2.7.16 vue-template-compiler@2.7.16

入口文件：

import MarkdownRender, { VueRendererMarkdown } from 'markstream-vue2'
import Vue from 'vue'
import 'markstream-vue2/index.css'

Vue.use(VueRendererMarkdown)

new Vue({
  render: h => h(MarkdownRender, { props: { content: '# Vue 2.7' } }),
}).$mount('#app')

在组件里使用 Composition API：

import { defineComponent, ref } from 'vue'

仓库示例：

playground-vue2（Vue 2.7 + Vite）

路径与启动命令：

bash

pnpm -C playground-vue2 dev

也可以在仓库根目录直接运行：

bash

pnpm play:vue2

Vue 3.x（使用 markstream-vue）

依赖：

bash

pnpm add markstream-vue vue@^3

入口文件：

import MarkdownRender from 'markstream-vue'
import { createApp, h } from 'vue'
import 'markstream-vue/index.css'

createApp({
  render: () => h(MarkdownRender, { content: '# Vue 3' }),
}).mount('#app')

如果你的工作区同时安装了 Vue 3，请确保 vue-demi 指向 Vue 2：

bash

pnpm vue-demi-switch 2

如果无法运行 vue-demi-switch（或希望只在某个应用里处理），可以在打包配置里强制把 vue-demi 指向 Vue 2 版本，避免出现 defineComponent is not a function：

// vue.config.js / webpack 配置
module.exports = {
  configureWebpack: {
    resolve: {
      alias: {
        'vue-demi$': 'vue-demi/lib/v2/index.cjs',
      },
    },
  },
}

可选的对等依赖

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

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

Vue 2.6.x 设置

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

bash

pnpm add @vue/composition-api

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

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

Vue.use(VueCompositionAPI)

在 Vue 2.6 组件里使用 Composition API：

import { defineComponent, ref } from '@vue/composition-api'

Vue 2.7.x 设置（无需插件）

Vue 2.7 已内置 Composition API，不要安装 @vue/composition-api：

import { defineComponent, ref } from 'vue'

功能加载器（Mermaid / KaTeX / D2）

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

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

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

同时记得导入必需的 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）：

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

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

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

html

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

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 初始化等）。如果你的目标是“让代码块正确高亮渲染”，更稳妥的方案是：

安装 Shiki 渲染依赖：

bash

pnpm add shiki stream-markdown

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

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

setCustomComponents({ code_block: MarkdownCodeBlockNode })

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）。

常见运行时报错排查

`defineComponent is not a function`

原因：vue-demi 处于 Vue 3 模式，但应用实际运行在 Vue 2.x。解决（任选其一）：

运行 pnpm vue-demi-switch 2
或在打包配置里把 vue-demi$ alias 到 vue-demi/lib/v2/index.cjs（见上文）

`provide() can only be used inside setup()` / `onMounted is called when there is no active component instance`

原因：monorepo/pnpm 工作区出现重复的 Vue 2 运行时实例。解决：确保全项目只使用 一个 Vue 2 实例：

在打包配置里将 vue$ alias 到应用自身的 Vue 2 运行时（参考 playground-vue2-cli/vue.config.js）
在 pnpm workspace 中用 overrides 固定 playground-vue2-cli>vue 为 Vue 2 版本

`Vue packages version mismatch`

原因：vue 与 vue-template-compiler 版本不一致。解决：对齐版本（例如都用 2.6.14 或都用 2.7.16），pnpm 可以用 packageExtensions / overrides 处理。

`Cannot read properties of undefined (reading 'props')`

原因：Vue 2.6 + Composition API 缺少 _setupProxy patch，或 Composition API 未安装。解决：

确保已安装 @vue/composition-api 并在入口执行 Vue.use(VueCompositionAPI)
升级到本仓库最新的 markstream-vue2 构建（已对 Vue 2.6 补丁 _setupProxy）

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 使用的所有工具类，从而获得更小的最终打包体积。

快速安装：所有功能

一次性启用所有功能：

bash

pnpm add shiki stream-markdown stream-monaco mermaid @terrastruct/d2 katex
# 或
npm install shiki stream-markdown stream-monaco mermaid @terrastruct/d2 katex

功能详情

代码语法高亮

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

bash

pnpm add shiki stream-markdown

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

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

setCustomComponents({ code_block: MarkdownCodeBlockNode })

Monaco 编辑器

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

bash

pnpm add stream-monaco

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

Mermaid 图表

渲染 Mermaid 图表：

bash

pnpm add mermaid

D2 图表

渲染 D2 图表：

bash

pnpm add @terrastruct/d2

KaTeX 数学公式渲染

数学公式渲染：

bash

pnpm add katex

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

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

快速测试

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

vue

<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：

vue

<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：

json

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

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

Vue 2 安装 ​

要求 ​

Composition API 版本兼容（Vue 2.6 / 2.7 / 3.x） ​

按版本快速开始（依赖 + 入口） ​

Vue 2.6.x ​

Vue 2.7.x ​

Vue 3.x（使用 markstream-vue） ​

可选的对等依赖 ​

Vue 2.6.x 设置 ​

Vue 2.7.x 设置（无需插件） ​

功能加载器（Mermaid / KaTeX / D2） ​

Vue CLI（Webpack 4）特别说明 ​

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

常见运行时报错排查 ​

defineComponent is not a function ​

provide() can only be used inside setup() / onMounted is called when there is no active component instance ​

Vue packages version mismatch ​

Cannot read properties of undefined (reading 'props') ​

Tailwind CSS 支持 ​

快速安装：所有功能 ​

功能详情 ​

代码语法高亮 ​

Monaco 编辑器 ​

Mermaid 图表 ​

D2 图表 ​

KaTeX 数学公式渲染 ​

快速测试 ​

使用 Composition API（Vue 2.7+） ​

TypeScript 支持 ​

Vue 2 安装

要求

Composition API 版本兼容（Vue 2.6 / 2.7 / 3.x）

按版本快速开始（依赖 + 入口）

Vue 2.6.x

Vue 2.7.x

Vue 3.x（使用 markstream-vue）

可选的对等依赖

Vue 2.6.x 设置

Vue 2.7.x 设置（无需插件）

功能加载器（Mermaid / KaTeX / D2）

Vue CLI（Webpack 4）特别说明

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

常见运行时报错排查

`defineComponent is not a function`

`provide() can only be used inside setup()` / `onMounted is called when there is no active component instance`

`Vue packages version mismatch`

`Cannot read properties of undefined (reading 'props')`

Tailwind CSS 支持

快速安装：所有功能

功能详情

代码语法高亮

Monaco 编辑器

Mermaid 图表

D2 图表

KaTeX 数学公式渲染

快速测试

使用 Composition API（Vue 2.7+）

TypeScript 支持