部署与启动说明（MxServiceCode / MxCAD 转换程序）

基于安装包实际目录与启动脚本整理。

一、程序位置（固定临时路径）

两类包：单独转换程序（MxConvert，仅含 mxcadassembly）与后端服务（MxServiceCode，同时含后端服务和转换程序，即完整超集）。下载地址以入口指引的"链接清单"为准（按需要 + 平台取对应行；Linux 包为 Ubuntu 20.04 x86_64 构建）。

固定临时路径（只下载一次，跨会话复用；系统清理临时目录后重新下载即可）：

Windows：%TEMP%\MxCAD\（%TEMP% 为用户 Temp 目录环境变量，命令中直接使用，无需手动展开）
Linux：/tmp/MxCAD/

按入口指引的排查步骤执行：先判断任务需要什么，再查看临时路径下有什么——什么都没有 → 按需要下载对应 zip（只需转换程序 → 单独 MxConvert 包；需要后端服务 → MxServiceCode 包，内含转换程序）解压到临时路径；只有转换程序 → 仅需转换程序时先做"三、试用版有效期检测"即可用，需要后端时清空重下后端包；已解包后端包 → 做过期检测 + 完整性验证，不完整清空重下。重新下载前必须先清空临时路径（各包目录结构固定，后端包是完整超集）。不要扫描用户机器其他目录。

解压后（Windows：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

MxServiceCode_TryVersion\    ← 解压后的顶层目录（与 zip 同名）
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← 官方后台开发教程（非 API 文档）
│   ├── MxServiceCode.sln        ← 解决方案文件
│   └── MxServiceCode\           ← 工程目录（以下命令在此执行）
│       ├── bin\node.exe          ← 内置 Node 运行时
│       ├── mxapp.js              ← 入口（命令行）
│       ├── src\                  ← TS 源码（mxcad\ 为 API 类，sample\ 为示例，MxCommand.ts 为命令注册）
│       ├── Mx2DNode.node         ← 原生模块
│       ├── package.json          ← npm run build 编译
│       ├── test.bat              ← 测试脚本
│       ├── empty_template.dwg    ← 空白模板
│       ├── A3.dwg / BT.DWG       ← 图框 / 图签示例图块
│       └── t1.dwg / tree.dwg     ← 测试图纸
└── MxCAD\
    └── Release\                 ← 格式转换程序目录（mxcadassembly.exe + 运行依赖 dll + mxcad_ini.json、mxcode.bin、mxiconv.data + **fonts\** + files\）

解压后（Linux：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

MxServiceCode_TryVersion\    ← 解压后的顶层目录（与 zip 同名）
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← 官方后台开发教程
│   └── MxServiceCode\           ← 工程目录（无 .sln；内置运行时为 node 而非 bin\node.exe，
│                                 另含 start_demo_MxServiceCode.sh、start_demo_systemlib_MxServiceCode.sh、Linux启动说明.txt）
└── Linux\
    └── MxCAD\                   ← 格式转换程序目录（mxcadassembly + 运行依赖 mx/so + mxcad_ini.json、mxcode.bin、mxiconv.data + **fonts\** + files\）

转换程序目录 = Windows 临时路径下 MxServiceCode_TryVersion\MxCAD\Release\、Linux 临时路径下 MxServiceCode_TryVersion\Linux\MxCAD\（单独 MxConvert 包则为 MxConvert_TryVersion\ 目录本身）；前端预览图纸所需字体 = 该目录下的 fonts\（复制它即可）。

二、运行 MxServiceCode 命令（无需启动任何服务）

命令方式为独立进程，直接调用内置 node：

Windows（工程目录下）：

bat

bin\node.exe mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json

Linux（工程目录下）：

bash

./node mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json linux=1

无参数运行 node mxapp.js 可打印版本信息与日志路径。

⚠️ 内置 Node 版本限制（实测）：bin\node.exe 为 v10.9.0，仅支持 CommonJS——ESM（import 语法 / .mjs）直接报 SyntaxError；也没有 fetch、可选链等新特性。用内置 node 写辅助脚本一律用 CommonJS（require）+ .js；需要 ESM 时改用系统 Node。

Linux 首次部署（权限配置）

bash

chmod 777 start_demo_MxServiceCode.sh
./start_demo_MxServiceCode.sh     # 脚本内已完成 mxcadassembly、mx/so、Mx2DNode.node、node 的 chmod

出错时改用 ./start_demo_systemlib_MxServiceCode.sh（使用 systemLib 目录下的原生库）。

三、格式转换程序 mxcadassembly（独立调用）

Windows（转换程序目录下，两种形式等价，按 shell 选）：

cmd / PowerShell（裸 JSON，即官方文档形式，无需编码）：

bat

mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}

Git Bash（百分号编码串 + 引号；该 shell 下裸 JSON 会返回 read file error，实测）：

mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"

Linux（转换程序目录下，裸 JSON 加单引号即可）：

bash

chmod -R 777 mxcadassembly ./mx/so/*
./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

（等价备选形式：./mxcadassembly '[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]'）

参数形式约定：程序接受两种等价形式——① 裸 JSON（官方文档形式，cmd / PowerShell / Linux bash 直接可用，bash 下用单引号包裹）；② 百分号十六进制编码串 + 一层方括号（如 {"a":1} → [%7B%22a%22%3A1%7D]，MxServiceCode 内部使用，Git Bash 必须用此形式）。MxServiceCode 内部的 MxUtility.callMxCadAssembly 已封装此逻辑，二开时优先通过 TS API 调用，不要手动拼命令。

⚠️ 常见坑（实测）
编码必须带 % 前缀；误用纯十六进制（如 7b2261223a317d）会返回 {"code":1,"message":"read file error"}
cmd.exe / 批处理中 % 是批处理变量引用：百分号编码串会被展开破坏（返回 {"code":1,"message":"read file error"}），cmd 下必须用裸 JSON 形式
Windows 上 python 可能是 Store 占位程序（静默无输出）；生成编码参数的临时脚本用内置 bin\node.exe
convert 命令不可用时（wgh 已废弃，见《MxServiceCode命令参考.md》详解 1），DWG→mxweb 以本独立调用为唯一途径；mxcad 前端只认 mxweb

试用版有效期检测

转换程序为试用版，期限 6 个月。临时路径中已有转换程序，使用前必须先做测试转换（命令行方式，无需 GUI；在转换程序目录执行，用包内自带测试图如 1.dwg，输出目录先建好）：
Windows（cmd / PowerShell）：mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}；Windows（Git Bash）：mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"；Linux：./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

返回 {"code":0,"message":"ok"} → 有效可用，直接使用。
返回非 0 → 读 %TEMP%\MxNode\mxcad_*.log 中的版本串（每次运行都会记录，格式实测样本：MxCAD TryVersion:7.0(2026-10-21 11:16)(64bit)(cooperate)）：
- 括号内日期（如 2026-10-21）= 试用起始日；当前日期 − 试用起始日 > 5 个月 → 过期，重新下载 zip 解压覆盖临时路径（地址见入口指引"链接清单"）
- 未过期 → 程序环境异常，按日志排错

常用 JSON 参数（详见官方《图纸转换详细说明》）：

转换：{"srcpath":"a.dwg","outname":"a.mxweb","outpath":"./out"}（路径相对转换程序目录；outname 后缀决定目标格式；mxweb 转 dwg 必须显式带 .dwg/.dxf；outpath 目录必须预先存在）
裁剪 DWG：{"cmd":"cut_dwg","bd_pt1_x":0,"bd_pt1_y":0,"bd_pt2_x":100,"bd_pt2_y":100,"srcpath":"a.dwg","outname":"cut.dwg"}
输出 PDF：{"srcpath":"a.dwg","outname":"a.pdf","outpath":"./out","ret_page_extents":true,"width":"2000","height":"2000","colorPolicy":"mono"}——不带 cmd 字段（带则返回 {"code":201}）；输出位置与其他转换规则一致：输出目录为 outpath（省略时回退转换程序目录），文件名为 outname（outname 为绝对路径时直接写该位置）
srcpath/outpath/outname 均支持绝对路径（含中文路径）
⚠️ 正式任务的产物必须写到用户要求的位置（用绝对路径或用户工作区相对路径），不要留在转换程序目录的 out\ 里：临时路径会被清空（重新下载前 / 系统清理），留在里面的产物（mxweb / pdf / 图片）会直接丢失；./out 仅用于试用检测
⚠️ cmd 参数域（如 print_to_pdf 等）属于 MxServiceCode 后端服务接口，mxcadassembly.exe 直调仅上述参数有效
若 mxcadassembly 是用户功能的运行时依赖（如"上传图纸在线打开"功能），注意临时路径不稳定问题（换包清空 / OS 自动清理），处理方式见《前端 mxcad 指南》1.1 节末尾"运行时转换功能"说明

四、二开工作流

修改 src/sample/*.ts 或新增文件（API 见《Mx2DNode二开API参考.md》）
在 src/MxCommand.ts 注册命令（见《MxServiceCode命令参考.md》第六节）
编译：npm run build（node_modules 已内置；如缺失用 bin\node.exe node_modules\typescript\bin\tsc --build）
用 bin\node.exe mxapp.js <命令> 参数=值 debug=1 验证

五、日志

路径：%TEMP%\MxNode（Linux 同规则）
每次命令结束输出 logs end；debug=1 时日志更详细
异常返回 {"code":-4,"message":"js程序异常，详细见日志"} 时查日志文件

六、附带资源说明

文件	用途
`empty_template.dwg`	空白模板，`Mx2DDraw.getEmptyTemplateDwgFilePath()` 指向它
`A3.dwg` / `BT.DWG`	图框 / 图签示例（BT 块含属性定义），testParamDrawTk 使用
`t1.dwg` / `tree.dwg`	测试图纸 / 图块（tree 图块用于 testParamDraw）
`mxcad_ini.json`（转换程序目录下）	转换程序配置（字体路径等），勿随意修改
`fonts\`	字体目录（DWG 中 SHX/TTF 字体依赖）

开始

指南

基础绘图

交互绘图

图纸编辑

数据库

最佳实践

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

相关文章

入门指南

MxCAD功能介绍

CAD 功能开发

应用集成

AI执行手册

后端参考文档

部署与启动说明（MxServiceCode / MxCAD 转换程序）

一、程序位置（固定临时路径）

解压后（Windows：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

解压后（Linux：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

二、运行 MxServiceCode 命令（无需启动任何服务）

Linux 首次部署（权限配置）

三、格式转换程序 mxcadassembly（独立调用）

试用版有效期检测

四、二开工作流

五、日志

六、附带资源说明

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

入门指南

MxCAD功能介绍

CAD 功能开发

应用集成

后端参考文档

部署与启动说明（MxServiceCode / MxCAD 转换程序） ​

一、程序位置（固定临时路径） ​

解压后（Windows：顶层只有一个目录 MxServiceCode_TryVersion\，与 zip 同名） ​

解压后（Linux：顶层只有一个目录 MxServiceCode_TryVersion\，与 zip 同名） ​

二、运行 MxServiceCode 命令（无需启动任何服务） ​

Linux 首次部署（权限配置） ​

三、格式转换程序 mxcadassembly（独立调用） ​

试用版有效期检测 ​

四、二开工作流 ​

五、日志 ​

六、附带资源说明 ​

部署与启动说明（MxServiceCode / MxCAD 转换程序）

一、程序位置（固定临时路径）

解压后（Windows：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

解压后（Linux：顶层只有一个目录 `MxServiceCode_TryVersion\`，与 zip 同名）

二、运行 MxServiceCode 命令（无需启动任何服务）

Linux 首次部署（权限配置）

三、格式转换程序 mxcadassembly（独立调用）

试用版有效期检测

四、二开工作流

五、日志

六、附带资源说明