mdye 视图插件内网开发指南

适用场景：开发机无法访问外网，需要在外网完成初始化后将项目整体复制到内网继续开发并提交。

---

原理说明

命令	是否需要外网	说明
mdye init	✅ 需要	从明道云服务器拉取模板、鉴权
mdye start	❌ 不需要	读取 mdye.json 中的内网地址连接
mdye push	❌ 不需要	读取 mdye.json 中的内网地址提交

核心思路：在外网完成初始化并将 mdye-cli 装入项目本地依赖，复制整个文件夹（含 node_modules）到内网后，修改 mdye.json 追加内网地址，再通过 npx 调用本地的 mdye-cli，无需全局安装任何工具。

---

内网机器环境要求

在复制到内网前，确认目标机器满足以下要求：

项目	要求
Node.js	> 20（node --version 确认）
npm	随 Node.js 附带，无需额外安装
其他工具	无需安装，mdye-cli 已内置在文件夹中

---

一、外网准备（一次性）

1. 安装全局 mdye-cli

npm install -g mdye-cli

2. 初始化项目

在外网明道云 Web 端「开发调试」面板复制 init 命令，在终端执行（React 基础示例模板）：

mdye init view --id <plugin-id> --template React

按提示输入项目文件夹名称（或直接回车使用默认名），完成后进入项目目录：

cd <项目文件夹名>

3. 安装项目依赖

npm install

4. 将 mdye-cli 装入本地依赖

这一步是关键，让 npx 在内网也能找到 mdye-cli，无需全局安装：

npm install mdye-cli --save-dev

完成后 package.json 的 devDependencies 中会出现 mdye-cli，node_modules/.bin/mdye 也会存在。

5. 验证本地 mdye 可用

npx mdye --version

能输出版本号（如 beta-0.0.34）即表示本地安装成功。

6. 此时的文件夹结构

<项目文件夹>/
├── node_modules/          ← 含项目依赖 + mdye-cli，必须一起复制
│   └── .bin/
│       └── mdye           ← npx 会调用这里
├── src/
│   └── App.js
├── .config/
├── mdye.json              ← 下一步需要修改这个文件
├── package.json           ← devDependencies 中有 mdye-cli
└── ...

---

二、复制到内网并修改配置

1. 复制文件夹

将整个项目文件夹（含 node_modules）复制到内网开发机。

⚠️ node_modules 体积通常在 200–400 MB，请确保复制完整，不要只复制源码文件。

2. 修改 mdye.json 指向内网

init 完成后，项目根目录的 mdye.json 初始内容如下：

{
  "id": "69e0ac9a0b05633ca6bd5895-69e5cb5f1d099d1e06e1498f",
  "template": "React",
  "version": "0.1"
}

在内网明道云 Web 端「开发调试」面板，可以看到对应插件的 init 命令，格式如下：

mdye init view --id xxx --template React --host https://p-demo.mingdaoyun.cn/wwwapi/ --webui https://p-demo.mingdaoyun.cn/

不需要执行这条命令，查看命令中是否包含 --host 和 --webui 参数，有则追加到 mdye.json，没有则忽略，原有属性保持不变。

字段	来源	说明
host	init 命令中的 --host 值	内网 API 地址，没有则不填
webui	init 命令中的 --webui 值	内网 Web 地址，没有则不填

例如命令中两个参数都有时：

{
  "id": "69e0ac9a0b05633ca6bd5895-69e5cb5f1d099d1e06e1498f",
  "template": "React",
  "version": "0.1",
  "host": "https://p-demo.mingdaoyun.cn/wwwapi/",
  "webui": "https://p-demo.mingdaoyun.cn/"
}

例如命令中只有 --host 时：

{
  "id": "69e0ac9a0b05633ca6bd5895-69e5cb5f1d099d1e06e1498f",
  "template": "React",
  "version": "0.1",
  "host": "https://p-demo.mingdaoyun.cn/wwwapi/"
}

---

三、内网开发与提交

启动本地调试

npx mdye start

mdye start 会读取 mdye.json 中的 host 和 webui，直接连接内网明道云。首次运行时会弹出内网授权页面完成登录。

提交代码

开发完成后：

npx mdye push -m "提交说明"

常用提交示例

npx mdye push -m "初始化"
npx mdye push -m "修复筛选逻辑"
npx mdye push -m "新增地图展示"

npx 会自动使用 node_modules/.bin/mdye，不会尝试从网络下载。

---

四、注意事项

• 如果 mdye-cli 有版本更新，需要回到外网重新执行 npm install mdye-cli --save-dev 后再次复制 node_modules。
• Node.js 版本需 > 20，可通过 node --version 确认。