as const不能用于jsdoc，因其是ts专有语法，jsdoc仅支持标准js语法和类型伪函数；正确做法是ts中用as const定义常量并导出类型，jsdoc中通过@type {typeof xxx[number]}引用推导出的字面量类型。
as const 本身不能直接用于 JSDoc
这是最容易踩的第一个坑：as const 是 TypeScript 编译器专用语法，JSDoc 注释里写 as const 会直接报错（SyntaxError: Unexpected token 'as'）。JSDoc 只支持标准 JS 语法 + 类型伪函数（如 import()），不解析 TS 特有断言。所以别在 /** @type {...} */ 里塞 as const —— 它根本不会被识别。
用 as const 声明常量，再用 @type 引用其推导出的字面量类型
真正可行的链路是：先在 TS 文件中用 as const 定义一个不可变值，让编译器推导出精确的字面量类型（比如 readonly ["user", "admin"] 或 { id: 1, name: "test" } & { readonly id: 1; readonly name: "test" }），然后在 JSDoc 中通过 @type 直接引用这个已存在的常量名或其类型。
- TS 文件中定义：
const ROLES = ["user", "admin"] as const; export type Role = typeof ROLES[number]; // "user" | "admin"
- JSDoc 中复用：
/** @type {Role} */ let currentRole = "user"; - 如果不想导出类型，也可直接引用：
/** @type {typeof ROLES[number]} */ let currentRole = "user";
对象嵌套时 as const 的深度限制与 JSDoc 替代方案
as const 对嵌套对象默认只做浅层冻结 —— 外层属性变成只读，但深层对象仍可能被修改（除非每层都显式加 as const）。而 JSDoc 没法补这个缺口，它只能标注类型，不能改变运行时行为。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 危险写法（看似只读，实则可改）：
const config = { api: { baseUrl: "https://api.example.com" }, features: { enabled: true } } as const; config.api.baseUrl = "http://hacked.com"; // ❌ TypeScript 报错（因为 api 是 readonly） config.features.enabled = false; // ❌ 同样报错 // 但注意：config.api 本身是对象字面量，其内部属性没被递归冻结 - 安全写法（逐层
as const）：const config = { api: { baseUrl: "https://api.example.com" } as const, features: { enabled: true } as const } as const; - JSDoc 中无法自动继承这种“多层只读”，必须手动写出完整字面量类型或依赖 TS 编译后生成的声明文件
为什么不能跳过 as const，直接在 JSDoc 里写字面量类型？
可以写，但维护成本爆炸。比如你想标注一个按钮状态数组：["primary", "secondary", "danger"]，在 JSDoc 里硬写 @type {readonly ["primary", "secondary", "danger"]} 看似可行，但一旦后端新增状态，你得同步改三处：数据源、JSDoc 类型、所有消费该数组的逻辑判断 —— 而用 as const 定义源头，再用 typeof XXX[number] 引用，改一处就全链更新。
更关键的是：JSDoc 不校验字面量值是否真实存在于数组中。如果你写 @type {"primary" | "warning"}，但实际数组里根本没有 "warning"，编辑器不会提醒；而 as const + typeof 是从真实值推导，天然保真。
真正容易被忽略的点在于：as const 的保护只作用于编译期类型检查，不阻止运行时篡改（比如通过 Object.defineProperty 绕过）。如果你需要运行时防护，得额外加 Object.freeze()，且必须作用于每一层嵌套对象 —— 这和 JSDoc 或类型系统完全无关，是纯 JS 行为。
