> **本文回答**：开始 vjcad 开发前应按照"安装 → MainView 配置 → initCadContainer 挂载 → await onLoad → 用 Engine"的顺序检查这 7 个 setup 子主题。

## 一、初始化的 6 步

1. `npm install vjcad`（或 yarn/pnpm），见 [install-and-mcp](install-and-mcp.md)。
2. 准备好一个有非零宽高的 DOM 容器（例如 `<div id="cad-app">` 设 `width:100% height:100%`）。
3. `new MainView({...})`：传入 `appname / version / wasmServiceUrl / serviceUrl / accessToken / sidebarStyle / fonts / locale / viewMode` 等，见 [mainview-init](mainview-init.md)。
4. `initCadContainer('cad-app', cadView)`：把 `MainView` 实例挂到容器。
5. `await cadView.onLoad()`：必须等待，`onLoad` 内部会等 PixiJS、WASM、字体、插件、URL 参数全部就绪。详见 [onload-lifecycle](onload-lifecycle.md)。
6. 绘图/文档 API（`Engine.addEntities`、`Engine.currentDoc`、`Engine.editor` 等）须在 `onLoad` 之后调用；`CommandRegistry.regist`、`Engine.eventManager.on` 在 `onLoad` 前调用也有效（命令表是静态数组、事件管理器是全局单例）。

## 二、按场景挑子主题

| 场景 | 子主题 |
|---|---|
| 安装 / 环境 / MCP 服务地址 | [install-and-mcp](install-and-mcp.md) |
| `MainView` 配置项详解 | [mainview-init](mainview-init.md) |
| `onLoad()` 在等什么、为什么必须等 | [onload-lifecycle](onload-lifecycle.md) |
| 字体（woff/ttf/shx）配置 | [fonts](fonts.md) |
| 中英文界面切换 / `t` / `registerMessages` | [locale-i18n](locale-i18n.md) |
| 只读查看模式（隐藏菜单/工具栏） | [viewer-mode](viewer-mode.md) |
| 状态栏 / 菜单 / Ribbon / 侧边栏全量定制 | [mainview-config](mainview-config.md) |

## 三、Top 初始化错误

1. 没 `await cadView.onLoad()` 就用 `Engine` → **不会报 undefined**：`Engine.currentDoc` 是懒建的孤儿文档、`Engine.pcanvas` 为 `null`、`Engine.addEntities` 静默丢弃；`Engine.eventManager` 是真单例。详见 [onload-lifecycle](onload-lifecycle.md) §三。
2. 容器 `<div>` 宽高为 0 或没设 `position` → 首屏黑屏。
3. 把 `new vjmap.Service()` / `new vjmap.Map()` 套到 vjcad → vjcad 不需要这些，只走 `MainView + initCadContainer`。
4. 写错 viewer 配置项（应是 `viewMode: "viewer"`，不是 `viewerMode: true`）。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/guide/quick-start.md`、`vjcad/doc/basic/index.md`、`vjcad/doc/guide/architecture.md`
- 示例：`vjcad/example/basic/01init.js`、`vjcad/example/basic/02onload.js`、`vjcad/example/basic/03viewermode.js`