vue-markdown-render

Appearance

Monaco 内部实现 ​

本文档介绍在 vue-markdown-render 中使用 monaco-editor 时的打包和运行时要点（用于在项目中集成大型编辑器时减少问题）。

安装 ​

bash
pnpm add stream-monaco

Vite 打包建议 ​

  • Monaco 使用 Web Worker 来处理语法高亮与语言服务；在生产环境下需要正确的 worker 配置。
  • 推荐使用 vite-plugin-monaco-editor-esm 或 vite-plugin-monaco-editor 来确保 worker 文件被正确打包。

示例：

ts
import monacoEditorPlugin from 'vite-plugin-monaco-editor'

export default defineConfig({ plugins: [monacoEditorPlugin()] })

避免 Failed to load Monaco worker 错误 ​

  • 确认插件将 worker 文件打包到可访问的路径（可通过插件提供的 customDistPath 配置来控制）。
  • 在构建产物中检查 worker 文件是否存在，并确认 CDN 或静态资源路径可访问。

如果你将 vue-markdown-render 发布为库，请确保使用者把 stream-monaco 作为 peer 依赖安装；否则在运行时找不到 Monaco worker 与 runtime。

运行时行为与性能 ​

  • 本库设计为当 CodeBlockNode 挂载时懒加载 Monaco，从而减少首次渲染时的包体积。仅在需要时才初始化 Monaco 编辑器。
  • 在大量 CodeBlock 的页面中，启用 viewportPriority 或在父组件中延迟加载可以显著降低内存占用并提升首屏速度。

打包到库的注意事项 ​

  • 当把本库打包进其他项目时，请在目标项目中正确配置 worker 路径或使用插件的选项来重新定位。
  • 考虑使用 preload 或 getUseMonaco() 在页面需要时预加载 Monaco，这样能改善用户首次打开大型文档时的响应。

常见故障排查 ​

  • 如果看到 Failed to load Monaco worker，先在浏览器网络面板（Network）中检查 worker 文件的请求与响应；资源 404 或路径不正确通常就是问题所在。
  • 如果在 SSR 场景报错，请确认 Monaco 仅在客户端初始化（使用动态导入或 onMounted 来隔离）。