install

本文回答：如何以 npm 或 CDN 方式安装 vjmap / vjmapext，加载顺序、版本对齐、TypeScript 支持。

一、npm 安装（推荐）

npm install vjmap vjmapext

• Node.js ≥ 16（推荐 18+）
• vjmapext 把 vjmap 声明为 peerDependency（>=1.0.161，见 mapext package.json）；npm ≥7 会自动安装 peer 依赖，但更稳妥的是两者显式一起装。建议 vjmap 与 vjmapext 使用同一时期发布的版本组合。
• vjmap 同时是浏览器包也提供 TypeScript 类型，直接 import vjmap from "vjmap" 即可。

1. 样式文件必须引入

import "vjmap/dist/vjmap.min.css"; // 不引入会缺控件样式

2. ESM / CommonJS 两种写法

import vjmap from "vjmap";
import { MapCadLayer, LineEnt, CircleEnt, TextEnt } from "vjmapext";

// 或 CJS
const vjmap = require("vjmap");
const { MapCadLayer } = require("vjmapext");

二、CDN / <script> 引入

<link rel="stylesheet" href="https://vjmap.com/demo/js/vjmap/vjmap.min.css" />
<script src="https://vjmap.com/demo/js/vjmap/vjmap.min.js"></script>

<!-- 只有需要 CAD 绘图能力时才需要加载 vjmapext（注意：与 vjmap 同在 /js/vjmap/ 目录下） -->
<script src="https://vjmap.com/demo/js/vjmap/vjmapext.min.js"></script>

全部 API 挂在全局 window.vjmap / window.vjmapext 上。

加载顺序规则

• vjmap.min.css 要放在 <head> 里尽早加载。
• vjmap.min.js 必须早于 vjmapext.min.js，否则 vjmapext 内部对 vjmap 的引用会失败（表现：执行时报 Cannot read properties of undefined (reading 'Map')）。
• 也不要把业务脚本放在这两个 <script> 之前执行。

三、Access Token

• 测试环境：https://vjmap.com/server/api/v1，可在 vjmap 官网 注册后获取个人 Access Token。
• 私有化部署：使用企业自有 URL + 自己的 Token。生产环境不要把长期 Token 硬编码在前端源码里，建议后端中转或使用 short-lived token。

四、TypeScript 类型

两个包都自带 .d.ts。对 MapCadLayer 等类型可直接：

import type { Map } from "vjmap";
import { MapCadLayer, type EntityBase } from "vjmapext";

五、常见错误排查

六、卸载 / 升级

npm uninstall vjmap vjmapext
# 或
npm install vjmap@latest vjmapext@latest

升级时建议同时升级两个包，并通读官方 changelog（CHANGELOG.md）。