@anov/gis-skills-cli 0.0.0-stage → 0.3.0

package/skills/using-anovgis/templates/combo1-vue3-vite.md

@@ -0,0 +1,295 @@
+> 本文件是 `skills/using-anovgis/SKILL.md` 的子文件 —— 模板组合 1（Vue 3 + Vite + 推荐控件 + 天地图 + 内网本地 SDK（默认组合））。
+> 由 using-anovgis 路由进入，不要被别的 skill 直接引用。
+
+#### 组合 1：Vue 3 + Vite + 推荐控件 + 天地图 + 内网本地 SDK ⭐ 推荐（默认）
+
+> ⚠️ **v0.2.10 重写**：实测发现真正 bug 只有 1 个——`baseLayer: ANOVGIS.ImageryType.TDT` 触发 `_layerIndex on string 'tdt'` 错。删 baseLayer 行就够（对齐官方 `anov-gis-demo-vue3-main` 模板——官方根本不传 baseLayer）。**v0.2.9 关于 vite 7 必须升 vite 8 的判断是错的，撤销**（实测 vite 7 + 裸 @anov/gis + 不传 baseLayer，playwright 零报错）。
+>
+> ⚠️ **v0.2.12**：版本号跟齐官方 `anov-gis-demo-vue3-main` 模板（vite 8 + vue 3.5.43 + plugin-vue 6.0.9）。vite 7 / vite 8 实测都能跑（见 v0.2.10 定论），选官方版本号是为了与团队现存 Vue 3 项目保持一致，减少版本认知负担。
+
+**`package.json`**（v0.2.12 跟齐官方 `anov-gis-demo-vue3-main`）：
+```json
+{
+  "name": "anov-gis-vue3-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@anov/gis": "^1.8.6",
+    "vue": "^3.5.43"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.9",
+    "vite": "^8.3.0",
+    "vite-plugin-static-copy": "^4.1.1"
+  }
+}
+```
+
+**`vite.config.ts`**（v0.2.7.3 跟齐官方 `anov-gis-demo-vue3-main` 模板，**移除 `optimizeDeps.exclude`**）：
+```ts
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+// anov-gis Vue 3 + Vite 8 最简配置
+// 完全对齐官方 anov-gis-demo-vue3-main 模板
+// SDK v1.8.6 + Cesium 1.143
+export default defineConfig({
+  plugins: [
+    vue(),
+    viteStaticCopy({
+      targets: [{
+        src: 'node_modules/@anov/gis/dist/resources/**/*',
+        dest: 'anov-gis-sdk',
+        rename: { stripBase: 5 },
+      }],
+    }),
+  ],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+})
+```
+
+> **v0.2.7.3 修订**：playwright 实测官方模板（vite 8.3.0 + vue 3.5.43，无 `exclude`）**零报错**运行。v0.2.7.2 的 `optimizeDeps.exclude` 是绕路（避开 esbuild 预构建撞名），但官方模板本身用 vite 8 预构建也能跑。撞名的两个 `function Yi(` 在不同嵌套层级（实测 -62 vs -56），不会在同一 scope shadow。
+
+> **v0.2.10 修订（定论）**：v0.2.9 的「vite 7 必须升 vite 8」是**误诊**——`exclude` 确实会引入 `does not provide an export named 'default'`（UMD 无 default），但**什么 optimizeDeps 配置都不需要**：v0.2.10 playwright 实测 vite 7 + 裸 @anov/gis + 不传 baseLayer **零报错**。真正的 bug 只有 `baseLayer: ANOVGIS.ImageryType.TDT`（字符串 `'tdt'` 被塞进图层集合，v0.2.9 看到的 P10 撞名错其实也是它——`queueReprojectionCommands` 打在字符串上）。删 baseLayer 行即可，vite 7 / vite 8 都行。
+
+> **v0.2.12**：默认模板版本号回到官方 vite 8（`vite ^8.3.0` / `vue ^3.5.43` / `@vitejs/plugin-vue ^6.0.9`）。**不是**因为 vite 7 不能跑（v0.2.10 已实测 vite 7 零报错），而是从 0 创建项目统一用官方版本号，与团队现存 Vue 3 项目保持一致。
+
+**`index.html`**：
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>anov-gis Vue3 Starter</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>
+```
+
+**`src/main.ts`**：
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import ANOVGIS from '@anov/gis'
+import '@anov/gis/dist/index.css'
+
+// ⚠️ 必须在 new Viewer 之前（CDN/UMD 也遵守同一规则）
+// 用 import.meta.env.BASE_URL 让 dev (/) / build (./) 都能正确解析 anov-gis-sdk 路径
+ANOVGIS.setBaseUrl(import.meta.env.BASE_URL + 'anov-gis-sdk/')
+
+createApp(App).mount('#app')
+```
+
+**`src/App.vue`**（v0.2.9 修订：删 `baseLayer: ANOVGIS.ImageryType.TDT`，对齐官方模板）：
+```vue
+<script setup lang="ts">
+// ⚠️ viewer 必须模块级 let — 严禁 ref()/reactive()（避免每帧 setter 风暴）
+let viewer: any = null
+
+onMounted(() => {
+  // 不要传 baseLayer: ANOVGIS.ImageryType.*（SDK v1.8.6 内部 new ImageryLayer('TDT')
+  // 会报 "Cannot create property '_layerIndex' on string 'tdt'"）
+  // 要加底图就用 viewer.imageryLayers.addImageryProvider()（构造后模式）
+  viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    // 标准 demo 不需要时间轴/CZML 相关控件
+    timeline: false,
+    animation: false,
+    // 顶部控件（默认全开 — 与 anovgis-pitfalls § P-v0.2.4 一致）
+    baseLayerPicker: true,
+    fullscreenButton: true,
+    homeButton: true,
+    sceneModePicker: true,
+    navigationHelpButton: true,
+    // 信息栏
+    showMapInfo: true,
+    copyRight: false,
+    showFPS: false,
+    drillPick: false,
+  })
+})
+
+onBeforeUnmount(() => {
+  viewer?.destroy()
+  viewer = null
+})
+</script>
+
+<template>
+  <div id="cesiumContainer" style="width:100vw;height:100vh"></div>
+</template>
+```
+
+**`src/globalConfig.ts`**（key / 服务地址）：
+```ts
+// ⚠️ v0.2.7 硬编码：默认用 ANOV-GIS 官方 demo key（SDK examples/src/mixins/mixin.js 公开测试 key）
+// 正式部署再替换为团队在 https://console.tianditu.gov.cn 申请的 key
+export const globalConfig = {
+  tdtKey: 'b832b9764939cbb0919148c548b669ba',
+}
+```
+
+**运行**：
+```bash
+npm install
+npm run dev
+# 打开 http://localhost:5173
+```
+
+**避坑（与本模板对照的常见错）**：
+
+| 错误做法 | 后果 | 对应陷阱 |
+|---|---|---|
+| `vite-plugin-static-copy@^1.0.0` + 没 `"type":"module"` | ESM 报错 | **P9** |
+| vite **7/8** + 裸 `@anov/gis` + 构造时传 `baseLayer` | `_layerIndex on string 'tdt'` / `queueReprojectionCommands` 错（v0.2.9 曾误诊为 vite 预构建） | **删 baseLayer（v0.2.10 定论，vite 7 / 8 实测均零报错）** |
+| `optimizeDeps.exclude:['@anov/gis']` | UMD 无 default 导出，浏览器 `import ANOVGIS` 报 `does not provide an export named 'default'` | **v0.2.7.2 已撤销——不需要任何 optimizeDeps 配置** |
+| 用旧 SDK 示例 `anov-gis-demo-vue3` 的 vite `^4.x` + static-copy `^0.17.0` | 能跑但 `optimizeDeps` 等生态已落后 | 推荐升级 |
+| `tdtKey: '替换为团队分配的 key'` 让用户去申请 | 增加摩擦 | 默认用 demo key |
+| 加 `@anov/vite-plugins` 协调包（hainan 风格） | 单 hello earth 项目过重,引入 `layout-designer` 服务 + 额外依赖 `@anov/cic-standard-sdk` | v0.2.7.2 移除,纯 vue+vite 即可 |
+| `baseLayer: ANOVGIS.ImageryType.TDT`（构造时传底图类型） | SDK v1.8.6 内部 `new ImageryLayer('TDT')` 报 `_layerIndex on string 'tdt'` | v0.2.9 修复（删 baseLayer,构造后用 `viewer.imageryLayers.addImageryProvider`） |
+| 仅 curl/grep 验证 vite 启动就 commit "修复" | 实际运行时跑 playwright 才发现有错 | **P11（验证后才能说修复）** |
+
+**验证命令**（跑通后**必跑**——不要只 curl 就 commit）：
+```python
+# playwright 端到端验证（不要省略！）
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    errors = []
+    page.on('pageerror', lambda e: errors.append(e.message))
+    page.on('console', lambda m: errors.append(m.text) if m.type == 'error' else None)
+    page.goto('http://localhost:5173/', wait_until='networkidle', timeout=30000)
+    import time; time.sleep(5)
+    print(f'errors: {len(errors)}')
+    for e in errors[:5]: print(f'  - {e[:200]}')
+    has_canvas = page.evaluate("!!document.querySelector('canvas')")
+    print(f'canvas: {has_canvas}')
+    browser.close()
+# 期望：errors: 0, canvas: True
+```
+
+---
+
+
+---
+
+## 变体：ESM 模块方式（`import` 引入，适合 webpack / vite / rollup）
+
+### B. ESM 模块方式（`import` 引入）适合 webpack / vite / rollup。
+
+```js
+// 来源: README.md L179-188
+import '@anov/gis/dist/index.css';
+import ANOVGIS from '@anov/gis';
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/');
+const viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    // ⚠️ 不要传 baseLayer（v0.2.10 实测 v1.8.6 会报 _layerIndex on string 错）——底图构造后 addImageryProvider
+});
+```
+
+
+---
+
+### D. Vue 3 + Vite 模板用 `vite-plugin-static-copy` 拷贝 Cesium 静态资源，AMD 报错用 webpack `IgnorePlugin` 兜底（`./punycode`/`./IPv6`/`./SecondLevelDomains`），模板 [anov-gis-vite](https://github.com/948033145/anov-gis-vite)。
+
+> 完整骨架见上方「§ NPM 引入」末尾 Vite 配置 + App.vue 示例。
+
+```ts
+// 来源: README.md L201 + cesium_1_143_umd_webpack_amd_error.md
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+export default defineConfig({
+    plugins: [vue(), viteStaticCopy({
+        targets: [{ src: 'node_modules/@anov/gis/dist/resources/*', dest: 'anov-gis-sdk/resources' }],
+    })],
+    build: { target: 'esnext' },
+    define: { CESIUM_BASE_URL: JSON.stringify('/anov-gis-sdk/resources/') },
+});
+```
+
+```vue
+<script setup lang="ts">
+// 来源: src/index.js L89-135（baseUrl 推断逻辑）
+import { onMounted, onBeforeUnmount } from 'vue';
+import ANOVGIS from '@anov/gis'; import '@anov/gis/dist/index.css';
+let viewer: any;
+onMounted(() => { viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+}); });
+onBeforeUnmount(() => viewer && viewer.destroy());
+</script>
+<template><div id="cesiumContainer" style="width:100%;height:100vh"></div></template>
+
+
+---
+
+## 变体：Vue 骨架 —— ❌ 错误 vs ✅ 正确
+
+铁律 1「3D 大对象严禁进响应式」的具体对照（来自 `using-anovgis` § 框架集成 3 条铁律）：
+
+**正确骨架（Vue 3 Composition API + Vite）**：
+
+```vue
+<!-- src/App.vue -->
+<script setup>
+import { onMounted, onBeforeUnmount } from 'vue'
+import ANOVGIS from '@anov/gis'
+
+let viewer = null  // 模块级 let，绝不放 ref()/reactive()
+
+onMounted(() => {
+  const Cesium = window.Cesium  // 唯一推荐写法
+  viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    baseLayerPicker: false, infoBox: false, selectionIndicator: false,
+    geocoder: false, animation: false, timeline: false,
+    contextOptions: { id: 'cesiumCanvas' },
+  })
+})
+
+onBeforeUnmount(() => {
+  viewer?.destroy()
+  viewer = null
+})
+</script>
+
+<template>
+  <div id="cesiumContainer" style="width:100vw;height:100vh"></div>
+</template>
+```
+
+**错误骨架（会导致主线程卡死）**：
+
+```vue
+<!-- ❌ 严禁 -->
+<script setup>
+import { ref } from 'vue'
+import ANOVGIS from '@anov/gis'
+
+// ❌ viewer 进了 ref，每帧 setter 触发响应式风暴
+const viewer = ref(null)
+onMounted(() => {
+  viewer.value = new ANOVGIS.Viewer('cesiumContainer', {})
+})
+</script>
+```

package/skills/using-anovgis/templates/combo2-vue2-cli.md

@@ -0,0 +1,119 @@
+> 本文件是 `skills/using-anovgis/SKILL.md` 的子文件 —— 模板组合 2（Vue 2 + Vue CLI + 推荐控件 + 天地图 + 内网本地 SDK）。
+> 由 using-anovgis 路由进入，不要被别的 skill 直接引用。
+
+#### 组合 2：Vue 2 + Vue CLI + 推荐控件 + 天地图 + 内网本地 SDK
+
+**`package.json`**：
+```json
+{
+  "name": "anov-gis-vue2-starter",
+  "version": "1.0.0",
+  "scripts": {
+    "serve": "vue-cli-service serve",
+    "build": "vue-cli-service build"
+  },
+  "dependencies": {
+    "@anov/gis": "^1.8.6",
+    "vue": "^2.7.16"
+  },
+  "devDependencies": {
+    "@vue/cli-service": "^5.0.0",
+    "copy-webpack-plugin": "^12.0.0",
+    "vue-template-compiler": "^2.7.16"
+  }
+}
+```
+
+**`vue.config.js`**：
+```js
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+module.exports = {
+  publicPath: '/',
+  configureWebpack: {
+    plugins: [
+      new CopyWebpackPlugin({
+        patterns: [{
+          from: 'node_modules/@anov/gis/dist/resources',
+          to: 'public/anov-gis-sdk/resources'
+        }]
+      })
+    ]
+  }
+};
+```
+
+**`src/main.js`**：
+```js
+import Vue from 'vue';
+import App from './App.vue';
+import ANOVGIS from '@anov/gis';
+import '@anov/gis/dist/index.css';
+
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/');
+
+Vue.config.productionTip = false;
+new Vue({ render: (h) => h(App) }).$mount('#app');
+```
+
+**`src/App.vue`**：
+```vue
+<template>
+  <div id="cesiumContainer" style="width:100vw;height:100vh"></div>
+</template>
+
+<script>
+import ANOVGIS from '@anov/gis';
+
+export default {
+  name: 'App',
+  mounted() {
+    this.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+      // ⚠️ 不要传 baseLayer: ANOVGIS.ImageryType.*（SDK v1.8.6 报 "_layerIndex on string 'tdt'"）——底图构造后用 addImageryProvider
+      contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+      geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+      timeline: true, animation: true,
+      baseLayerPicker: true, fullscreenButton: true,
+      homeButton: true, sceneModePicker: true, navigationHelpButton: true,
+      showMapInfo: true,
+    });
+  },
+  beforeDestroy() {
+    this.viewer && this.viewer.destroy();
+  },
+};
+</script>
+```
+
+---
+
+
+---
+
+## 变体：Vue 2 + vue-cli 配置与 Options API 写法
+
+### C. Vue 2 + vue-cli 模板用 `copy-webpack-plugin` 拷贝 `node_modules/@anov/gis/dist/resources` 到 `public/anov-gis-sdk/resources`，模板仓库 [anov-gis-vue2](https://github.com/948033145/anov-gis-vue2)。
+
+```js
+// 来源: README.md L200 + vue.config.js 模板约定
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+module.exports = {
+    publicPath: '/',
+    configureWebpack: { plugins: [new CopyWebpackPlugin({
+        patterns: [{ from: 'node_modules/@anov/gis/dist/resources', to: 'public/anov-gis-sdk/resources' }],
+    })] },
+};
+```
+
+```js
+// 来源: examples/.../basemap/tdtSatelliteImage.html L28-66
+export default {
+    mounted() {
+        window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+            contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+            geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+        });
+    },
+    beforeUnmount() { window.viewer && window.viewer.destroy(); },
+};
+```
+

package/skills/using-anovgis/templates/combo3-html-cdn.md

@@ -0,0 +1,107 @@
+> 本文件是 `skills/using-anovgis/SKILL.md` 的子文件 —— 模板组合 3（纯 HTML + UMD CDN + 极简控件 + 天地图 + 公网）。
+> 由 using-anovgis 路由进入，不要被别的 skill 直接引用。
+
+## CDN 引入（前置）
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <title>@anov/gis Demo</title>
+    <script src="https://unpkg.com/@anov/gis@1.7.7/dist/index.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/@anov/gis@1.7.7/dist/index.css">
+    <!-- ⚠️ 1.8.4 尚未发布到公共 CDN，使用 1.7.7 替代。本地 SDK 升级到 1.8.x 后请改用 npm 引入。-->
+    <style>
+        html, body, #cesiumContainer { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
+    </style>
+</head>
+<body>
+    <div id="cesiumContainer"></div>
+    <script>
+        // ⚠️ 必须在 new Viewer 之前调用
+        ANOVGIS.setBaseUrl('https://unpkg.com/@anov/gis@1.7.7/dist/resources/');
+        window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+            contextOptions: {
+                id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true },
+                showRenderLoopErrors: false,
+            },
+            geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+            baseLayerPicker: true, fullscreenButton: true, homeButton: true,
+            sceneModePicker: true, navigationHelpButton: true,
+            copyRight: false, showMapInfo: true,
+        });
+    </script>
+</body>
+</html>
+```
+
+> ⚠️ 必须通过 HTTP 服务打开（不能直接 `file://`），否则 Cesium 静态资源加载失败。
+
+
+#### 组合 3：HTML + UMD CDN + 极简 + 天地图 + 公网
+
+**`index.html`**（单文件，零构建）：
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>anov-gis Quick Demo</title>
+  <script src="https://unpkg.com/@anov/gis@1.8.6/dist/index.js"></script>
+  <link rel="stylesheet" href="https://unpkg.com/@anov/gis@1.8.6/dist/index.css">
+  <style>
+    html, body, #cesiumContainer { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
+  </style>
+</head>
+<body>
+  <div id="cesiumContainer"></div>
+  <script>
+    ANOVGIS.setBaseUrl('https://unpkg.com/@anov/gis@1.8.6/dist/resources/');
+    window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+      // ⚠️ 不要传 baseLayer: ANOVGIS.ImageryType.*（SDK v1.8.6 报 "_layerIndex on string 'tdt'"）——底图构造后用 addImageryProvider
+      contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+      geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+      // 极简 profile：全 false
+      timeline: false, animation: false,
+      baseLayerPicker: false, fullscreenButton: false,
+      homeButton: false, sceneModePicker: false, navigationHelpButton: false,
+      showMapInfo: false, copyRight: false, showFPS: false, drillPick: false,
+    });
+  </script>
+</body>
+</html>
+```
+
+**运行**：
+```bash
+npx http-server -p 8080
+# 打开 http://localhost:8080/
+```
+
+---
+
+
+---
+
+## 变体：UMD 全局方式（`<script>` 引入，适合快速验证 / 无构建工具）
+
+### A. UMD 全局方式（`<script>` 引入）适合快速验证 / 无构建工具。`@anov/gis` 挂到全局 `ANOVGIS`。
+```html
+<!-- 来源: README.md L156-160 -->
+<script src="./anov-gis-sdk/index.js"></script>
+<link rel="stylesheet" href="./anov-gis-sdk/index.css">
+<script src="./anov-gis-sdk/applyfn.js"></script><!-- 业务级 API，可选 -->
+```
+
+```js
+// 来源: examples/.../basemap/tdtSatelliteImage.html L49-66
+window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true }, showRenderLoopErrors: false },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    baseLayerPicker: true, fullscreenButton: true, homeButton: true,
+    sceneModePicker: true, navigationHelpButton: true, copyRight: false, showMapInfo: true,
+});
+```
+
+> CDN 1.7.7 仍可用，1.8.x 需改 NPM。

package/skills/using-anovgis/templates/combo4-vanilla-webpack.md

@@ -0,0 +1,91 @@
+> 本文件是 `skills/using-anovgis/SKILL.md` 的子文件 —— 模板组合 4（Vanilla JS + webpack 5 + 完整控件 + ArcGIS + 内网）。
+> 由 using-anovgis 路由进入，不要被别的 skill 直接引用。
+
+#### 组合 4：Vanilla JS + webpack + 完整 + ArcGIS + 内网
+
+**`package.json`**：
+```json
+{
+  "name": "anov-gis-webpack-starter",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "webpack --mode production"
+  },
+  "dependencies": { "@anov/gis": "^1.8.6" },
+  "devDependencies": {
+    "copy-webpack-plugin": "^12.0.0",
+    "html-webpack-plugin": "^5.5.0",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.0",
+    "webpack-dev-server": "^5.0.0"
+  }
+}
+```
+
+**`webpack.config.js`**（含 AMD 报错兜底）：
+```js
+const path = require('path');
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const webpack = require('webpack');
+
+module.exports = {
+  entry: './src/main.js',
+  output: {
+    path: path.resolve(__dirname, 'dist'),
+    filename: 'bundle.[contenthash].js',
+    publicPath: '/',
+  },
+  plugins: [
+    new HtmlWebpackPlugin({ template: './index.html' }),
+    new CopyWebpackPlugin({
+      patterns: [{
+        from: 'node_modules/@anov/gis/dist/resources',
+        to: 'anov-gis-sdk/resources'
+      }]
+    }),
+    // Cesium 1.143 UMD AMD 报错兜底（P4 陷阱）
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^\.\/locale$/,
+      contextRegExp: /moment$/,
+    }),
+  ],
+};
+```
+
+**`src/main.js`**：
+```js
+import '@anov/gis/dist/index.css';
+import ANOVGIS from '@anov/gis';
+
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/');
+
+window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+  // ⚠️ 不要传 baseLayer（v0.2.10 实测 v1.8.6 会报 _layerIndex on string 错）——底图构造后 addImageryProvider
+  contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+  geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+  // 完整 profile
+  timeline: true, animation: true,
+  baseLayerPicker: true, fullscreenButton: true,
+  homeButton: true, sceneModePicker: true, navigationHelpButton: true,
+  showMapInfo: true, copyRight: true, showFPS: true, drillPick: true,
+});
+```
+
+**`index.html`**：
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>anov-gis Webpack Starter</title>
+</head>
+<body>
+  <div id="cesiumContainer" style="width:100vw;height:100vh"></div>
+</body>
+</html>
+```
+
+---
+