create-swdg-frontend 0.1.6 → 0.2.0

package/template/.prettierrc.cjs

@@ -1,10 +1,10 @@
-module.exports = {
-  semi: true, // 在语句末尾添加分号
-  singleQuote: true, // 使用单引号而不是双引号
-  trailingComma: 'es5', // 多行时尽可能打印尾随逗号
-  bracketSpacing: true, // 在对象的括号之间添加空格
-  tabWidth: 2, // 指定每个缩进级别的空格数
-  useTabs: false, // 使用空格代替制表符
-  endOfLine: 'lf', // 维持现有的行尾（防止在不同操作系统间出现问题）
-  printWidth: 80, // 推荐值是 80 或 120
-};
+module.exports = {
+  semi: true, // 在语句末尾添加分号
+  singleQuote: true, // 使用单引号而不是双引号
+  trailingComma: 'es5', // 多行时尽可能打印尾随逗号
+  bracketSpacing: true, // 在对象的括号之间添加空格
+  tabWidth: 2, // 指定每个缩进级别的空格数
+  useTabs: false, // 使用空格代替制表符
+  endOfLine: 'lf', // 维持现有的行尾（防止在不同操作系统间出现问题）
+  printWidth: 80, // 推荐值是 80 或 120
+};

package/template/.stylelintignore

@@ -1 +1 @@
-src/style/**
+src/style/**

package/template/.stylelintrc.json

@@ -1,6 +1,12 @@
-{
-  "extends": ["stylelint-config-standard", "stylelint-config-recommended-vue"],
-  "rules": {
-    "no-empty-source": null
-  }
-}
+{
+  "extends": ["stylelint-config-standard", "stylelint-config-recommended-vue"],
+  "rules": {
+    "no-empty-source": null,
+    "selector-class-pattern": [
+      "^([a-z][a-z0-9]*(-[a-z0-9]+)*)(__([a-z][a-z0-9]*(-[a-z0-9]+)*))*(-{1,2}([a-z][a-z0-9]*(-[a-z0-9]+)*))*?$",
+      {
+        "message": "Use kebab-case or BEM (block__element--modifier)"
+      }
+    ]
+  }
+}

package/template/README.md

@@ -1,36 +1,99 @@
-# Frontend Framework (Vue 3 + TypeScript + Vite)
-
-面向小型开发团队的通用前端框架模板，提供清晰目录、可复用示例、统一配置与约定。
-
-## 目录结构
-
-project
-├── interface/ # 📝 业务模型接口定义
-├── public/ # 🌐 公共资源，打包会直接打进根目录
-├── src
-│ ├── api/ # 🔌 请求后端接口
-│ ├── assets/ # 🖼 静态资源
-│ ├── components/ # 🧩 公共基础组件
-│ ├── directive/ # ⚡ 全局指令
-│ ├── layout/ # 📐 布局组件
-│ ├── router/ # 🛣 路由配置
-│ ├── stores/ # 🗄 全局状态管理
-│ ├── styles/ # 🎨 全局样式
-│ ├── utils/ # 🛠 工具类
-│ └── views/ # 📄 业务页面
-├── tests/ # 🧪 测试目录
-│ ├── unit/ # 单元测试（Vitest）
-│ ├── e2e/ # E2E 测试
-│ ├── setup.ts # 测试环境配置
-│ └── utils/ # 测试工具函数
-├── types/ # 📋 全局类型声明
-├── vitest.config.ts # 🧪 Vitest 配置
-└── package.json
-
-## 示例说明
-
-- `src/api/`：`modules/demo.ts` 演示接口调用
-- `src/stores/`：`useCounter.ts` 演示 Pinia Store
-- `src/directive/`：`focus.ts` 演示自定义指令
-- `src/layout/`：`BasicLayout.vue` 演示布局壳
-- `src/views/Test`：演示使用 store + api + composable
+# SWDG Frontend Framework
+
+面向团队的 **Vue 3 + TypeScript + Vite** 标准模板与脚手架（`create-swdg`）。
+
+设计参考 Google / Meta / Microsoft 内部生成器常见模式：
+
+- **薄 CLI、厚模板**：逻辑在模板仓库迭代，CLI 只做拷贝与特性裁剪
+- **Feature flags**：重型能力（GIS）默认关闭，按需 opt-in
+- **示例与业务分离**：`src/views/examples/` 仅 dev 路由，生产自动剔除
+- **可验证**：创建后可跑 `typecheck`；模板发布前 `validate-template`
+- **可追溯**：生成 `.swdg/manifest.json` 记录创建参数
+
+## 如何使用本项目
+
+**完整说明（环境、路由、接口、GIS、构建）** → **[docs/ONBOARDING.md](docs/ONBOARDING.md)**
+
+```bash
+pnpm install
+cp .env.example .env   # 含 VITE_FEATURE_GIS、代理地址
+pnpm dev               # http://localhost:3000 ，改 .env 后需重启
+```
+
+| 你想做的事   | 怎么做                                                                 |
+| ------------ | ---------------------------------------------------------------------- |
+| 跑起来看效果 | 首页 `/#/` → 开发示例卡片 → Cesium / Store 示例                        |
+| 加一个新页面 | `src/views/模块名/index.vue` → 自动得到 `/#/模块名`                    |
+| 调后端接口   | `src/api/` + 开发代理 `/demo` → `VITE_DEMO_PROXY_TARGET`               |
+| 开三维地图   | `.env` 设 `VITE_FEATURE_GIS=true`，用 `CesiumViewer` 或 `createViewer` |
+| 提交前检查   | `pnpm verify`                                                          |
+
+维护模板 / 发 npm → [docs/MAINTAINER.md](docs/MAINTAINER.md) · 测试门禁 → [docs/TESTING.md](docs/TESTING.md)
+
+## 创建新项目（脚手架）
+
+```bash
+pnpm create swdg my-app
+# 或
+npx create-swdg-frontend my-app
+```
+
+交互会询问：项目名、**是否 GIS（默认否）**、是否安装依赖、是否 Git、是否 typecheck 校验。
+
+```bash
+# 非 GIS 项目（推荐多数后台类应用）
+pnpm create swdg my-app --no-gis --install
+
+# GIS 项目
+pnpm create swdg my-app --gis --install
+```
+
+## 目录结构
+
+```
+src/
+├── api/           # 接口
+├── components/    # 公共组件
+├── layout/
+├── router/        # 约定式路由（views 下文件即路由）
+├── stores/
+├── utils/
+├── views/         # 业务页面
+│   └── examples/  # 开发示例（生产构建剔除）
+interface/
+types/
+docs/
+```
+
+## Cesium / GIS（可选特性）
+
+启用后包含：`cesium`、`vite-plugin-static-copy`、开发中间件、`/#/examples/cesium`。
+
+- 底图：OpenStreetMap（无需 Ion token）
+- 可选：`VITE_CESIUM_ION_ACCESS_TOKEN`
+
+```ts
+import { createViewer } from '@utils/cesium';
+```
+
+## 维护者与发布
+
+见 [docs/MAINTAINER.md](docs/MAINTAINER.md)。
+
+```bash
+pnpm verify                              # 本地质量门禁
+cd create-swdg && pnpm sync-template     # 同步模板
+cd create-swdg && node scripts/validate-template.mjs
+```
+
+## 脚本
+
+| 命令             | 说明                                 |
+| ---------------- | ------------------------------------ |
+| `pnpm dev`       | 开发                                 |
+| `pnpm build`     | 构建                                 |
+| `pnpm typecheck` | TS 检查                              |
+| `pnpm verify`    | typecheck + lint（日常）             |
+| `pnpm test:ci`   | 发布门禁（全量，见 docs/TESTING.md） |
+| `pnpm gen:api`   | OpenAPI 生成                         |
+| `pnpm release`   | 先跑 test:ci，再发布 npm 包          |

package/template/auto-imports.d.ts

@@ -0,0 +1,10 @@
+/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// noinspection JSUnusedGlobalSymbols
+// Generated by unplugin-auto-import
+// biome-ignore lint: disable
+export {}
+declare global {
+
+}

package/template/commitlint.config.cjs

@@ -1,64 +1,64 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional'],
-  rules: {
-    // 提交消息的类型必须是以下之一
-    'type-enum': [
-      2, // 错误级别
-      'always',
-      [
-        'feat', // 新功能
-        'fix', // 修复问题
-        'update', // 更新现有功能
-        'docs', // 文档更新
-        'style', // 代码格式（不影响功能）
-        'refactor', // 重构代码（不影响功能）
-        'perf', // 性能优化
-        'test', // 添加或修改测试
-        'chore', // 杂项更新（比如构建工具）
-        'revert', // 回滚提交
-        'build', // 构建系统或外部依赖变更
-        'ci', // CI/CD 配置或脚本修改
-      ],
-    ],
-    // 允许范围为空
-    'scope-empty': [0, 'never'],
-    'scope-case': [2, 'always'],
-    // 提交消息的主题不能为空
-    'subject-empty': [2, 'never'],
-    // 不限制提交消息结尾的标点符号
-    'subject-full-stop': [0, 'never'],
-    // 限制提交消息的主题长度
-    'header-max-length': [2, 'always', 72],
-    // 'message-case': [2, 'always', 'lower-case'],
-  },
-  prompt: {
-    messages: {
-      skip: ':跳过',
-      max: '最多输入 %d 个字符',
-      min: '至少输入 %d 个字符',
-      emptyWarning: '请填写有效内容',
-      upperLimitWarning: '长度超过限制',
-      lowerLimitWarning: '长度不足',
-    },
-    questions: {
-      type: {
-        description: '选择提交类型（如：feat, fix, docs等）',
-      },
-      scope: {
-        description: '影响的模块范围（如：auth, api等，可选）',
-      },
-      subject: {
-        description: '简要描述本次提交（限72个字符以内）',
-      },
-      body: {
-        description: '详细描述本次提交（可选）',
-      },
-      breaking: {
-        description: '列出任何破坏性更新（可选）',
-      },
-      footer: {
-        description: '关联的issue，例如：#123, #456（可选）',
-      },
-    },
-  },
-};
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // 提交消息的类型必须是以下之一
+    'type-enum': [
+      2, // 错误级别
+      'always',
+      [
+        'feat', // 新功能
+        'fix', // 修复问题
+        'update', // 更新现有功能
+        'docs', // 文档更新
+        'style', // 代码格式（不影响功能）
+        'refactor', // 重构代码（不影响功能）
+        'perf', // 性能优化
+        'test', // 添加或修改测试
+        'chore', // 杂项更新（比如构建工具）
+        'revert', // 回滚提交
+        'build', // 构建系统或外部依赖变更
+        'ci', // CI/CD 配置或脚本修改
+      ],
+    ],
+    // 允许范围为空
+    'scope-empty': [0, 'never'],
+    'scope-case': [2, 'always'],
+    // 提交消息的主题不能为空
+    'subject-empty': [2, 'never'],
+    // 不限制提交消息结尾的标点符号
+    'subject-full-stop': [0, 'never'],
+    // 限制提交消息的主题长度
+    'header-max-length': [2, 'always', 72],
+    // 'message-case': [2, 'always', 'lower-case'],
+  },
+  prompt: {
+    messages: {
+      skip: ':跳过',
+      max: '最多输入 %d 个字符',
+      min: '至少输入 %d 个字符',
+      emptyWarning: '请填写有效内容',
+      upperLimitWarning: '长度超过限制',
+      lowerLimitWarning: '长度不足',
+    },
+    questions: {
+      type: {
+        description: '选择提交类型（如：feat, fix, docs等）',
+      },
+      scope: {
+        description: '影响的模块范围（如：auth, api等，可选）',
+      },
+      subject: {
+        description: '简要描述本次提交（限72个字符以内）',
+      },
+      body: {
+        description: '详细描述本次提交（可选）',
+      },
+      breaking: {
+        description: '列出任何破坏性更新（可选）',
+      },
+      footer: {
+        description: '关联的issue，例如：#123, #456（可选）',
+      },
+    },
+  },
+};

package/template/docs/MAINTAINER.md

@@ -0,0 +1,77 @@
+# 脚手架维护指南（负责人）
+
+对标大厂实践：**薄 CLI、厚模板、特性开关、可验证、可版本化**。
+
+## 架构
+
+```
+frontend-framework/     # 模板源仓库（本仓库）
+├── create-swdg/        # npm 包 create-swdg-frontend
+│   ├── bin/index.js    # CLI 入口
+│   ├── lib/            # 提示、特性剥离、manifest
+│   ├── stubs/          # 无 GIS 时的配置替身
+│   └── template/       # sync-template 同步产物
+└── swdg/               # 全局 CLI 包装
+```
+
+## 发布到 npm
+
+### 方式 A：打 tag 自动发布（推荐）
+
+**一次性配置**
+
+1. 登录 [npmjs.com](https://www.npmjs.com/)，确认账号已验证邮箱  
+2. 确认包名 **`create-swdg-frontend`**、**`swdg`** 在你账号下（首次需未被占用）  
+3. npm → Access Tokens → **Generate New Token**  
+   - 类型：**Granular**（Publish 权限）或 **Classic**（Automation）  
+4. GitHub 仓库 [Inupedia/swdg-frontend](https://github.com/Inupedia/swdg-frontend) → **Settings → Secrets and variables → Actions**  
+5. 新建 Secret：`NPM_TOKEN` = 上一步的 token  
+
+**每次发版**
+
+```bash
+# 1. 本地确认测试通过
+pnpm test:ci
+
+# 2. 提交并推到 GitHub（如有未 push 的改动）
+git push github main
+
+# 3. 打 tag 并推送（版本号与 tag 一致，格式 vX.Y.Z）
+git tag v0.2.0
+git push github v0.2.0
+```
+
+4. 打开 **Actions → Release to npm**，等待 workflow 完成  
+5. 验证：`npm view create-swdg-frontend version`、`npm view swdg version`
+
+CI 会：从 tag 解析版本 → `test:ci` → 发布 `create-swdg-frontend` → 发布 `swdg`。
+
+### 方式 B：本地手动发布
+
+```bash
+pnpm test:ci
+pnpm release 0.2.0
+```
+
+详见 [TESTING.md](./TESTING.md)。
+
+## 特性（Feature Flags）
+
+| 特性  | 默认 | CLI                |
+| ----- | ---- | ------------------ |
+| `gis` | 关闭 | `--gis` / 交互选 Y |
+
+未启用 GIS 时会删除：cesium 依赖、vite 静态资源配置、`src/views/examples/cesium`、相关工具与组件。
+
+生成项目会写入 `.swdg/manifest.json` 记录创建时选项。
+
+## 模板质量门禁
+
+- `examples/` 路由：**生产构建自动排除**（见 `src/router/index.ts`）
+- 创建后可选 **typecheck 校验**（`--verify`）
+- 建议每月 sync 一次并打 tag
+
+## 勿再做的事
+
+- 不要把 Cesium 放进 `public/`（已改为 npm + vite 插件）
+- 不要在业务 `src/views/` 根下堆演示页，统一放 `examples/`

package/template/docs/ONBOARDING.md

@@ -0,0 +1,284 @@
+# 项目使用指南
+
+本文说明 **如何在本仓库或脚手架生成的项目中日常开发**。维护模板、发布 npm 见 [MAINTAINER.md](./MAINTAINER.md)。
+
+---
+
+## 一、两种使用方式
+
+| 方式               | 适合谁                           | 第一步                                                       |
+| ------------------ | -------------------------------- | ------------------------------------------------------------ |
+| **直接使用本仓库** | 团队统一模板、在 monorepo 上迭代 | `git clone` → `pnpm install`                                 |
+| **脚手架新建项目** | 每个业务一条独立仓库             | `pnpm create swdg my-app`（见根目录 [README](../README.md)） |
+
+两种方式的项目结构、命令、路由约定 **一致**；脚手架可通过 `--gis` / `--no-gis` 裁剪 Cesium 相关文件。
+
+---
+
+## 二、环境要求与首次启动
+
+**要求**
+
+- Node.js **22+**
+- **pnpm** 9+（推荐；也可用 npm / yarn）
+
+**首次启动**
+
+```bash
+pnpm install
+cp .env.example .env    # 必做：复制环境变量
+pnpm dev
+```
+
+浏览器会自动打开（默认 `http://localhost:3000`）。路由为 **Hash 模式**，首页地址形如 `http://localhost:3000/#/`。
+
+**页面内指南**：开发模式下首页自带 **PPT 式翻页**（共 10 页），也可访问 `/#/examples/guide` 全屏阅读。支持方向键、`←` / `→` 按钮与底部圆点跳转。
+
+> 修改 `.env` 后需要 **重启** `pnpm dev`，Vite 才会加载新变量。
+
+---
+
+## 三、环境变量说明
+
+在根目录 `.env` 中配置（参考 `.env.example`）：
+
+| 变量                           | 是否必填            | 说明                                             |
+| ------------------------------ | ------------------- | ------------------------------------------------ |
+| `VITE_DEMO_PROXY_TARGET`       | 调 `/demo` 接口时   | 开发代理目标，如 `http://127.0.0.1:8888`         |
+| `VITE_FEATURE_GIS`             | GIS 项目建议 `true` | 为 `true` 时首页显示 Cesium 入口；`false` 则关闭 |
+| `VITE_CESIUM_ION_ACCESS_TOKEN` | 否                  | 使用 Cesium Ion 资产时填写；默认 OSM 底图可不填  |
+
+**GIS 看不到地图入口？**
+
+1. 确认 `.env` 中有 `VITE_FEATURE_GIS=true`
+2. 重启 `pnpm dev`
+3. 开发环境未配置时也会默认尝试开启 GIS（见 `useFeatureGis`），生产构建仍以 env 为准
+
+---
+
+## 四、本地开发能做什么
+
+启动 `pnpm dev` 后：
+
+| 入口               | 路径（Hash）         | 说明                         |
+| ------------------ | -------------------- | ---------------------------- |
+| 首页               | `/#/`                | 应用壳；开发模式下有示例卡片 |
+| Store / Alert 示例 | `/#/examples/test`   | Pinia、全局 Alert            |
+| Cesium 示例        | `/#/examples/cesium` | 三维地图（需 GIS 开启）      |
+
+`src/views/examples/` 下的页面 **不会打进生产包**（见 `src/router/index.ts`），可放心放演示代码。
+
+---
+
+## 五、目录与路径别名
+
+### 主要目录
+
+```
+src/
+├── views/          # 页面（约定式路由，见下一节）
+├── components/     # 公共组件
+├── layout/         # 布局组件
+├── api/            # 接口请求
+├── stores/         # Pinia
+├── utils/          # 工具、composables、cesium 封装
+├── styles/         # 全局样式（global.css、shell.css）
+├── router/         # 路由入口（一般不用改）
+interface/          # 业务 TS 类型
+types/              # 全局类型、env.d.ts
+docs/               # 文档
+```
+
+### 路径别名（import 时用）
+
+| 别名            | 指向                     |
+| --------------- | ------------------------ |
+| `@/`            | `src/`                   |
+| `@components/`  | `src/components/`        |
+| `@views/`       | `src/views/`             |
+| `@api/`         | `src/api/`               |
+| `@stores/`      | `src/stores/`            |
+| `@utils/`       | `src/utils/`             |
+| `@composables/` | `src/utils/composables/` |
+| `@interface/`   | `interface/`             |
+| `@layout/`      | `src/layout/`            |
+
+示例：
+
+```ts
+import { useCounterStore } from '@stores/useCounter';
+import { useFeatureGis } from '@composables/useFeatureGis';
+import MyCard from '@components/MyCard/index.vue';
+```
+
+---
+
+## 六、约定式路由（重要）
+
+无需手写 `routes` 数组：`src/views` 下每个 `*.vue` 会自动注册。
+
+**规则简述**
+
+- 文件路径 → URL 路径（去掉 `views`、去掉 `/index`）
+- 目录名会转为 **kebab-case**
+
+| 文件                                    | 访问路径                |
+| --------------------------------------- | ----------------------- |
+| `src/views/index.vue`                   | `/#/`                   |
+| `src/views/UserList/index.vue`          | `/#/user-list`          |
+| `src/views/system/RoleManage/index.vue` | `/#/system/role-manage` |
+| `src/views/examples/test/index.vue`     | `/#/examples/test`      |
+
+**新增业务页步骤**
+
+1. 创建 `src/views/YourFeature/index.vue`
+2. 保存后刷新浏览器，直接访问 `/#/your-feature`
+3. 在页面内用 `useRouter()` / `<router-link to="...">` 跳转
+
+```vue
+<!-- src/views/Dashboard/index.vue -->
+<template>
+  <div>业务大屏</div>
+</template>
+```
+
+---
+
+## 七、接口与代理
+
+- 接口代码放在 `src/api/`
+- 开发环境已配置代理：请求 **`/demo`** 会转发到 `VITE_DEMO_PROXY_TARGET`
+
+```ts
+// 示例：axios 请求会走 vite proxy
+// GET http://localhost:3000/demo/xxx  →  VITE_DEMO_PROXY_TARGET/demo/xxx
+```
+
+从 OpenAPI 生成客户端：
+
+```bash
+pnpm gen:api
+```
+
+（具体配置见 `scripts/gen-api.cjs`）
+
+---
+
+## 八、状态与全局能力
+
+- **Pinia**：`src/stores/`，已接入持久化插件
+- **全局 Alert**：`useAlert()`（`@composables/useAlert`）
+- **全局组件**：在 `src/utils/components` 注册
+- **指令**：如 `v-focus`（`src/directive/`）
+
+示例页 `/#/examples/test` 演示了 Store + Alert 的用法。
+
+---
+
+## 九、GIS / Cesium（可选）
+
+启用条件：`package.json` 含 `cesium`，且 `.env` 中 `VITE_FEATURE_GIS=true`（或使用脚手架 `--gis` 创建）。
+
+**在业务页中嵌入地图**
+
+```vue
+<template>
+  <CesiumViewer class="map-host" />
+</template>
+
+<script setup lang="ts">
+import CesiumViewer from '@components/CesiumViewer/index.vue';
+</script>
+
+<style scoped>
+.map-host {
+  width: 100%;
+  height: 480px;
+}
+</style>
+```
+
+**或自行创建 Viewer**
+
+```ts
+import { createViewer, destroyViewer } from '@utils/cesium';
+```
+
+- 默认 **OpenStreetMap** 底图，一般不需要 Ion Token
+- 开发时 Workers/Assets 由 `scripts/vite-plugin-cesium-dev.ts` 提供
+- 生产构建会复制 `dist/cesium/`，`base: './'` 适合静态部署
+
+---
+
+## 十、常用命令
+
+```bash
+pnpm dev            # 开发（端口 3000，自动打开浏览器）
+pnpm build          # 生产构建 → dist/
+pnpm preview        # 本地预览构建结果
+pnpm typecheck      # TypeScript 检查
+pnpm lint:all       # ESLint + Stylelint + Prettier 检查
+pnpm lint:fix       # 自动修复 ESLint
+pnpm test:run       # 单元测试（Vitest）
+pnpm verify         # typecheck + lint（提交前建议）
+```
+
+---
+
+## 十一、构建与部署
+
+```bash
+pnpm build
+```
+
+产物在 `dist/`：
+
+- `index.html`、JS/CSS 在 `assets/`
+- 若启用 GIS，另有 `cesium/` 静态资源目录
+
+部署到任意静态服务器（Nginx、OSS、GitHub Pages 等）即可；注意站点需能访问 **相对路径** 资源（已设置 `base: './'`）。
+
+预览构建：
+
+```bash
+pnpm preview
+```
+
+---
+
+## 十二、推荐日常流程
+
+1. `cp .env.example .env`，按需改代理与 GIS
+2. `pnpm dev`，从首页示例熟悉 Store / 地图
+3. 在 `src/views/` 下新增业务目录
+4. 在 `src/api/`、`src/stores/` 补充接口与状态
+5. 提交前执行 `pnpm verify`
+
+---
+
+## 十三、脚手架创建新项目（摘要）
+
+```bash
+pnpm create swdg my-app
+cd my-app
+pnpm dev
+```
+
+- 交互默认 **不启用 GIS**；三维项目请选 Y 或加 `--gis`
+- 生成目录含 `docs/ONBOARDING.md`（与本文同步）和 `.swdg/manifest.json`（记录创建选项）
+
+更多参数：`create-swdg` 包内 `pnpm create swdg --help` 或根 [README](../README.md)。
+
+---
+
+## 十四、遇到问题
+
+| 现象                   | 处理                                                               |
+| ---------------------- | ------------------------------------------------------------------ |
+| 首页没有 Cesium 卡片   | `.env` 加 `VITE_FEATURE_GIS=true` 并重启 dev                       |
+| 地图白屏 / Worker 报错 | 确认已 `pnpm install`，重启 dev；看控制台是否 404 `cesium/Workers` |
+| 改 env 不生效          | 必须重启 `pnpm dev`                                                |
+| 新页面 404             | 确认文件在 `src/views/` 下且路径符合约定；Hash 地址带 `#`          |
+| TS 路径报错            | 使用 `@/` 等别名，与 `tsconfig.json` 的 `paths` 一致               |
+
+仍无法解决时，把浏览器控制台与终端完整报错发给维护人。