内网环境下md-editor-v3部署实战：依赖、资源与接口链路完整方案

简介：针对md-editor-v3在内网环境下无法加载外网资源接口的常见问题，这一资源包提供了完整的本地化解决方案。它面向需要在内网或离线环境部署Markdown编辑功能的开发者，将编辑器运行所需的静态资源统一打包，规避了因外网访问受限导致的样式丢失、插件失效等隐患。资源包共含25个文件，以CSS和JS为主：CSS部分涵盖多款代码高亮主题与明暗配色方案，便于适配不同页面风格；JS部分则实现数学公式渲染（KaTeX）、代码高亮（highlight）、图片裁剪（cropper）及全屏等核心交互能力。整体压缩包仅919KB，轻量易部署，可直接内置于项目静态目录或上传至内网服务器，适用于政务云、企业内网等受限网络环境中的前端项目。目前已有169人学习下载，适合作为内网项目的前端依赖包使用。通过它，开发者省去逐一下载和配置CDN链接的时间，开箱即用地获得完整的Markdown编辑体验，并可按需挑选主题，提升集成效率；资源清单简洁清晰，便于后续维护与二次扩展。

1. 我先重新审视了一下问题：md-editor-v3 在内网到底卡在哪

内网环境下用 md-editor-v3，表面看问题就一句话："外网资源接口不通，编辑器跑不起来"。但你真去排查时，会发现这句话掩盖了至少三种完全不同的故障：依赖根本装不上、页面加载时外部资源 404、以及业务接口调不通。我一开始就是把它们混在一起处理，结果绕了很多弯路。

先说依赖问题。md-editor-v3 不是一个自包含的单文件组件，它背后有一整套依赖树：CodeMirror 5 负责代码编辑，highlight.js 负责代码高亮，还有官方扩展比如@vavt/md-editor-extension-katex（公式渲染）和@vavt/md-editor-extension-mermaid（流程图）。更麻烦的是，这些依赖还有自身的依赖，比如@codemirror/language、@codemirror/state、@codemirror/view这一层。在能联网的开发机上一切都好说，npm install几分钟搞定；到了内网机器上，npm 默认往官方源发请求，网络不通就卡死，要么报ECONNREFUSED，要么超时重试到让人崩溃。

再说资源问题。项目里如果舍得省事，可能直接在index.html塞了一堆 CDN 链接，比如 highlight.js 的主题 CSS、katex 的字体文件、github-markdown 的预览样式。这种写法在外网项目里很常见，性能也好，可一到内网，页面加载时浏览器就去请求那些公网 CDN 域名，结果自然是失败，编辑器区域白屏或者样式错乱。

最后是接口问题。md-editor-v3 本身不会自动帮你上传图片，它通过onUploadImg事件把文件交给你处理。如果你的项目把上传接口写成了公网地址，或者没有配置任何代理，内网浏览器发出的请求根本无法到达那个服务，图片传不上去，编辑器功能就不完整。

我把这些问题按"构建期—运行期—接口期"三个层次拆开，处理顺序也定了：先把依赖装好，再做资源本地化，最后统一处理接口链路。每一步对应的工具和排错手段都不同。下面详细说。

2. 依赖安装：私有 npm 源和离线包，怎么选怎么配

2.1 有私有 npm 仓库时的配置方式

我们公司的内网里没有现成的 npm 仓库，但我用同样思路验证过私有源方案，强烈建议有条件的话优先搭一个。用 Verdaccio 或 Nexus 在内网服务器上搭建一个 npm 代理仓库，开发机的.npmrc指向它：

registry=http://192.168.10.20:4873

这个配置建议放在项目根目录，不要用npm config set registry全局设置，否则会影响同一台机器上的所有 Node 项目。设置完执行npm install，如果私有源已经缓存过 md-editor-v3 和相关依赖，几秒钟就能装完。

需要注意版本同步问题。md-editor-v3 发版频率并不低，如果你的package.json锁定的是^4.19.0，私有源里却没有这个版本，安装会直接报No matching version found。解决方式有两个：要么在有网机器上npm pack md-editor-v3@4.19.0生成 tgz 包后导入私有源，要么把版本区间放宽，比如改成^4.15.0，让 npm 自动选择私有源里已有的版本。

还有一个容易忽略的点：配置好私有源之后，确认一下 npm 是否还在尝试访问其他源。如果package-lock.json里明确记录了每个包的resolved地址，而这些地址还是公网 npm 源，那 npm 仍然会直连外网。这种情况要给.npmrc加上：

registry=http://192.168.10.20:4873 replace-registry-host=always

我之前就在这里栽过跟头，锁文件里的 resolved 一直是外网地址，改了 registry 也没起作用。

2.2 完全离线环境的安装办法

如果内网连私有 npm 仓库都没有，那就得用更直接的方案。我实际测试过两种：离线 tgz 包和整个 node_modules 拷贝。

离线 tgz 包的操作流程是这样的。在有网机器上先执行一次完整的npm install，然后把关键依赖打成压缩包：

npm pack md-editor-v3@4.19.0 npm pack codemirror@5.65.16 npm pack highlight.js@11.10.0

把这些.tgz文件传到内网机器后，在项目里安装：

npm install ./md-editor-v3-4.19.0.tgz ./codemirror-5.65.16.tgz ./highlight.js-11.10.0.tgz

但这里有个隐藏问题：md-editor-v3 的 dependencies 不止这几个包，还有@codemirror/lang-*、@codemirror/language、@codemirror/state、@codemirror/view以及@vavt/util等。手动打 tgz 包很容易漏，漏一个就要重新走一遍拷贝流程，效率很低。

所以我更推荐直接用 node_modules 整体迁移。在有网机器上装好依赖，确认项目能正常启动，然后删除node_modules/.vite这种本地缓存目录，把整个node_modules压缩，传到内网机器解压。实测下来，只要内网机器的操作系统架构、Node 版本和原机器差距不大，项目直接npm run dev就能跑起来。这个方法的缺点是后续新增依赖又要重复一遍流程，但作为冷启动的第一版，是最省心可靠的。

2.3 安装完成后的快速自检

依赖装完先别急着开发，花两分钟确认一下安装结果：

ls node_modules/md-editor-v3/package.json && node -p "require('./node_modules/md-editor-v3/package.json').version" ls node_modules/@codemirror ls node_modules/highlight.js npm ls md-editor-v3

npm ls的输出要重点看有没有UNMET DEPENDENCY或invalid标记。如果出现peer冲突，优先调整package.json里的版本范围再装一次。在内网环境多排查一轮就意味着多一次文件传输，前置检查做细一点，后面反而省事。

3. 资源本地化：把所有远程加载改成项目内引用

3.1 样式、主题和字体如何处理

依赖安装完成只是第一步。很多人在内网打开页面，编辑器依然白屏或样式扭曲，原因就是样式文件来自外网 CDN。

md-editor-v3 的标准引用方式是这样的：

import { MdEditor } from 'md-editor-v3' import 'md-editor-v3/lib/style.css'

这种写法在 Vite 项目里会被正常打包，CSS 会生成到本地静态资源目录，不需要外部请求，所以问题不出在这。真正出问题的是你把额外的主题 CSS 写成了公网地址，比如在main.js里直接引用了：

import 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11/build/styles/github.min.css'

你可能觉得这写法太蠢，但实际项目中很多人图省事真的会这么干，尤其是有现成文档抄的时候。处理办法是下载到本地再导入。在能联网的机器上执行：

curl -O https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11/build/styles/github.min.css

把这个 CSS 文件放到项目的src/styles/目录下，然后改成相对路径引入：

import './styles/github.min.css'

同样的逻辑适用于所有外部资源：任何 CDN 链接都要本地化，任何http(s)://的静态资源引用都要替换成项目内路径。

3.2 扩展插件里的外链陷阱

如果项目里用了 md-editor-v3 的扩展生态，坑会更深。以@vavt/md-editor-extension-katex为例，它的文档里推荐的加载方式可能包含 katex 的 CDN 链接，而且公式渲染还需要 katex 的字体文件。katex 的字体文件通常有几 MB，如果你的部署环境没法访问外网，公式会一直渲染不出来。

解决思路和上面一致：把 katex 完整地安装为本地 npm 依赖，扩展初始化时指向本地资源路径。下面是一个兼容本地和内网环境的方式：

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

mermaid 扩展也一样。@vavt/md-editor-extension-mermaid默认行为可能动态加载 CDN 上的 mermaid 脚本，内网环境下流程图、时序图全部空白。改成：

npm install mermaid

然后在使用扩展的地方把本地 mermaid 实例传进去，而不是依赖扩展内部从 CDN 加载。

排查这类资源问题，最有效的是浏览器开发者工具。项目跑起来后打开 Network 面板，把请求过滤设置为http，逐个看请求域名是否是你内网服务器的 IP 或本机 localhost，只要有公网域名出现，就是一个潜在故障点。这个扫描过程要仔细，有时候一不留神就会漏掉某一个插件内部的资源引用。

3.3 构建产物的资源路径对齐

资源全部本地化后，还有最后一个隐藏问题：打包后资源路径不对。如果项目部署在内网服务器的子路径下，比如http://192.168.10.50/docs-admin/，Vite 默认的base是/，那么打包生成的 assets 目录引用会是/assets/xxx.css，而实际部署路径却是/docs-admin/，Nginx 找不到文件，页面一片白。

vite.config.js里需要显式设置：

export default defineConfig({ base: '/docs-admin/', server: { host: '0.0.0.0', port: 5173 } })

这一步不需要为 md-editor-v3 单独做任何特殊配置，它是整个项目层面的统一路径处理。但因为它影响所有静态资源，所以必须检查。部署到内网 Nginx 后，访问页面右键查看源码，确认 CSS 和 JS 文件的实际请求地址带上了docs-admin前缀，并且服务器上能访问到对应的文件。

4. 接口链路改造：从代理到图片上传的完整配置

4.1 开发阶段 Vite 代理配置

业务上最常见的场景是图片上传接口指向了外网文件服务，内网环境根本访问不到。我的处理方法是：内网开发时，所有请求先发给 Vite dev server，再由 dev server 代理转发到内网服务，绕开公网链路。

vite.config.js中示例配置：

export default defineConfig({ server: { host: '0.0.0.0', port: 5173, proxy: { '/api': { target: 'http://192.168.10.30:8080', changeOrigin: true } } } })

changeOrigin: true一定要开。它会把请求头里的Host字段改写为目标服务的地址，很多内网服务会对Host做白名单校验，不开这个参数就会遇到 403。

4.2 生产环境 Nginx 反向代理

开发环境代理只服务于本机调试，上线部署时后端接口的转发必须由 Nginx 完成。配置如下（示意）：

server { listen 80; server_name 192.168.10.50; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://192.168.10.30:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

这里有个细节容易让人踩坑：proxy_pass的 URL 末尾是否带/，决定了转发时是否保留/api前缀。带尾斜杠时，请求/api/upload会被重写成/upload转发到后端；不带尾斜杠时，请求路径会原样转发。具体选哪种，以后端接口的实际路由设计为准，改配置前先确认清楚。

4.3 图片上传的具体实现

md-editor-v3 的图片上传必须通过onUploadImg事件接管。下面是我一直在用的实现，已经经过内网项目验证：

<template> <MdEditor v-model="content" :onUploadImg="handleUploadImg" style="height: 500px" /> </template> <script setup> import { MdEditor } from 'md-editor-v3' import 'md-editor-v3/lib/style.css' const handleUploadImg = async (files, callback) => { const urls = await Promise.all( files.map(async (file) => { const formData = new FormData() formData.append('file', file) const response = await fetch('/api/upload', { method: 'POST', body: formData }) if (!response.ok) { throw new Error(`Upload failed: ${response.status}`) } const data = await response.json() return data.url }) ) callback(urls) } </script>

这段逻辑看起来不复杂，但有三个隐藏细节值得注意。

第一，files是文件数组，粘贴或拖拽图片时可能同时上传多张，所以用了Promise.all并行上传。第二，callback是 md-editor-v3 提供的回调函数，必须在上传完成后把 URL 数组传回去，编辑器才会把图片 Markdown 语法插入到文本流里。如果漏掉这个回调，上传请求其实成功发起了，接口也返回了地址，但编辑器界面上没有任何反馈，非常隐蔽。第三，接口返回的数据结构每个后端都不一样，data.url这个字段名要和你后端实际返回的契约为准，有时候是data.path，有时候是嵌套在data.data.url，例子里只是最标准的写法。

除了图片上传，保存内容的onSave事件也可以走同样的思路：把 Markdown 文本提交到/api/save，由代理转发到内网后端，只改事件回调里的请求地址和参数结构，其他保持不变。

5. 排错速查表与几条独家经验

5.1 高频问题对照表

我整理了自己实际遇到的高频问题和对应解法，可以直接对照排查：

排查逻辑有个通用原则：先打开浏览器的 Network 面板，确认请求到底有没有发出去、服务器有没有响应。这一步能快速区分是前端代码问题、代理配置问题还是后端服务问题，不用靠猜。

5.2 我的几条实操心得

经验一，验证前置。在联网机器上把 md-editor-v3 的完整功能先跑通，包括扩展插件、图片上传、保存事件，确认业务逻辑没问题后再迁移到内网。这样一旦出问题，你能判断是内网资源引用导致的，而不是业务代码本身的锅。

经验二，写一个外链扫描脚本。我写过一个简单的 Python 脚本，扫描src目录下所有.vue、.js、.css文件，用正则匹配http(s)://的字符串，把结果列出来逐一核对。这个脚本在内网项目中可以反复使用，不只针对 md-editor-v3，所有组件的资源引用都能查到。

经验三，别迷信内网里碰巧能访问的外网。有些内网环境可能开放了少数白名单域名，能访问某个 CDN，但访问另一个就失败。这种"半通"状态最坑人，因为你很难确定哪些请求会失败。最稳妥的做法是全部资源本地化，统一走项目内引用，不依赖任何外网可达性。

经验四，内网机器的 Node 版本提前确认。Vue 3 + Vite 项目对 Node 版本有硬性要求，Node 16 以下可能会遇到 Vite 启动失败或语法解析报错。我就遇到过开发机 Node 12 导致 md-editor-v3 源码编译报错的情况，换到 Node 18 后一切正常。这个检查看起来无关紧要，实际影响却非常大。

我个人认为，内网环境下接入 md-editor-v3，本质不是组件配置问题，而是资源管理能力的问题。把"外网依赖"这个概念拆成依赖安装、静态资源、接口链路三层，每层都有对应解法，整个接入过程就能变得可预期、可复现。如果你也在内网折腾这个编辑器，建议按我上面这个顺序走一遍，能少走不少弯路。

本文还有配套的精品资源，点击获取