typescript 配合 jsdoc 可在不改后缀、不重写逻辑前提下，为 .js 文件提供接近 .ts 的类型校验能力，但需满足三个硬性条件：tsconfig.json 中必须同时启用 allowjs: true 和 checkjs: true，jsdoc 注释语法严格合规（如 @param {string} name 有效，@param name {string} 无效），且所有依赖模块须有可用类型定义（@types/xxx 或内建 .d.ts）。
直接上结论：TypeScript 配合 JSDoc 能在不改后缀、不重写逻辑的前提下，为纯 .js 文件提供接近 .ts 的类型校验能力，但必须满足三个硬性条件——tsconfig.json 正确启用 checkJs 和 allowJs，JSDoc 注释语法严格合规，且所有依赖模块（包括第三方库）有可用类型定义（@types/xxx 或内建 .d.ts）。
为什么 checkJs: true 必须和 allowJs: true 一起开
TypeScript 编译器默认忽略 .js 文件。只设 checkJs: true 不设 allowJs: true，tsc 会直接跳过所有 JS 文件，连语法解析都不做，更别说类型检查了。反过来，只开 allowJs 不开 checkJs，JS 文件会被编译进输出目录（比如转成 ES5），但完全不报类型错误——等于白配。
正确配置示例（tsconfig.json）：
{
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"noEmit": true,
"strict": false,
"moduleResolution": "node",
"lib": ["ES2020"]
},
"include": ["src/**/*.js"]
}
-
noEmit: true是关键：避免把 JS 文件误编译成新文件，干扰构建流程 -
strict: false推荐初期使用：JSDoc 类型推导不如 TS 原生强，开 strict 容易因隐式 any 报错中断 CI -
include必须显式列出 JS 路径，不能只靠files—— 否则 tsc 可能漏掉子目录下的文件
JSDoc 注释里哪些写法 TypeScript 实际能识别
TypeScript 对 JSDoc 的支持不是全量的，只认特定标签和语法。常见失效写法包括：@param {string} name - 用户名 没问题，但 @param name {string} - 用户名 就会被忽略；@returns {number} 有效，@return {number}（少 s）就无效。
真正被 tsc 解析的常用标签：
-
@type {string | number}：用于变量、属性、函数返回值（如/** @type {string[]} */ const list = [];） -
@param {Date} date：必须紧贴函数声明上方，且参数名要一致 -
@returns {Promise<user>}</user>：注意尖括号要转义为和 <code>> -
@typedef+@property：可定义复杂对象结构（但嵌套深时容易推导失败）
特别注意：@template 和泛型推导在 JS 文件中基本不可用，别指望它能像 TS 那样处理 Array<t></t> 这类高级泛型。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
CI 中运行类型检查时为什么总报 “Cannot find module”
这是最常卡住上线的坑。TypeScript 在检查 JS 文件时，会尝试解析所有 import 和 require 的目标模块，并加载其类型定义。如果某个依赖没提供 .d.ts，或你用了动态 require('./' + name)，tsc 就会报 Cannot find module 'xxx' 或 Could not find a declaration file。
解决路径只有三条：
- 给缺失类型定义的包装
@types/xxx（优先查 npm） - 用
// @ts-ignore注释屏蔽单行（仅限明确知道安全的场景，比如 mock 工具） - 在
tsconfig.json的compilerOptions.types中显式排除干扰项，或用skipLibCheck: true（慎用，会跳过所有第三方类型检查）
另外，Node.js 内置模块（如 fs、path）需要确保 lib 选项包含对应环境，比如 "lib": ["ES2020", "DOM"] 不够，还得加 "NodeJS" 才能识别 fs.promises 类型。
生产环境同步校验的关键是“检查时机”和“错误粒度”
很多人以为配完就能在 npm run build 里看到类型错误，其实不然。tsc 默认只检查语法和基础类型，对运行时行为（比如 API 返回字段是否真存在）无能为力。真正的“同步”，是指每次提交前，在 pre-commit hook 或 CI 流程中执行 npx tsc --noEmit --project tsconfig.json，且把 exit code > 0 当作构建失败。
但要注意：JSDoc 校验无法覆盖动态 key 访问（obj[unknownKey]）、eval、JSON.parse 结果等场景。这些必须靠运行时校验（如 zod）补位。也就是说，JSDoc + TypeScript 是第一道防线，不是最后一道。
