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

## 一、npm 安装（推荐）

```bash
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. 样式文件必须引入

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

### 2. ESM / CommonJS 两种写法

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

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

## 二、CDN / `<script>` 引入

```html
<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 官网](https://vjmap.com/) 注册后获取个人 Access Token。
- 私有化部署：使用企业自有 URL + 自己的 Token。生产环境**不要把长期 Token 硬编码在前端源码里**，建议后端中转或使用 short-lived token。

## 四、TypeScript 类型

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

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

## 五、常见错误排查

| 报错 | 原因 |
|---|---|
| `vjmap.Map is not a constructor` | CDN 版 `vjmap.min.js` 未加载或顺序错 |
| `Cannot read properties of undefined (reading 'addEntity')` | `MapCadLayer` 没 `addControl` 就用 |
| `style is not loaded` / 控件没样式 | 忘了 `import "vjmap/dist/vjmap.min.css"` |
| openMap reject，`e.status === 403`（body `{code:7, msg:"Token is invalid"}`） | Token 缺失、错或过期（401 则是服务未激活/超用户数）；非 2xx 不进 `res.error`，要 `try/catch` |
| `vjcommon is not defined` / `Cannot find module 'vjcommon'` | 官方 demo 站示例用的辅助脚本 `vjcommon.min.js`（`selectFeatures`/`clearHighlight`/`getGeoJsonBounds` 等）**不在 npm 包里、也没单独发布**——它只随演示站点 `vjmap.com/demo/js/vjmap/vjcommon.min.js` 分发。npm 工程照抄示例时要删掉 `vjcommon.*` 调用或自行实现对应逻辑（查询/高亮可用 `map.queryRenderedFeatures` 与 `enableLayerClickHighlight` 等原生 API 替代） |

## 六、卸载 / 升级

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

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