tsconfig.json 必须同时启用 allowjs 和 checkjs，否则 jsdoc 类型注释（如 @type）在 .js 文件中不会被识别；strict: false 用于渐进迁移，skiplibcheck: true 加速构建。
tsconfig.json 中必须启用 allowJs 和 checkJs
不开启这两个选项，JSDoc 类型注释在 .js 文件里根本不会被 TypeScript 编译器识别。即使写了 /** @type {string} */，tsc 也只会当普通注释跳过。
常见错误是只开 allowJs、漏掉 checkJs，结果类型检查形同虚设。正确配置片段如下：
{
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"strict": false,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
-
strict: false是渐进式迁移的关键：避免一次性报几千个错误，先让核心模块跑起来 -
skipLibCheck: true可跳过 node_modules 下的类型检查，提速明显 - 如果项目含大量第三方 JS 库，建议额外加
"noImplicitAny": false，否则未标注的函数参数会直接报错
用 @type 替代 TS 类型声明，但注意 import() 的写法
在 JS 文件中不能写 import type { Config } from './types'，但可以用 JSDoc 的 import() 表达式做类型引用——这是唯一安全跨包取类型的方案。
错误示例（JS 文件中直接写 TS 语法）：
/** @type {Config} */ // ❌ Config 未定义，且无导入
const config = { port: 3000 };
正确写法（显式引用 + 内联类型）：
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
/** @type {import('./types').Config} */
const config = { port: 3000 };
-
import()是 JSDoc 伪函数，不参与运行时加载，纯编译期解析 - 路径必须是相对或绝对路径，不能是 npm 包名缩写（如
@/config），除非你配了baseUrl+paths - 嵌套类型如
import('./api').UserResponse['data']在 VS Code 中支持良好，但部分旧版 tsc 会报错，建议优先拆成顶层类型导出
apidoc 生成文档时，typescript.enabled 必须为 true
apidoc 默认只解析 JSDoc 注释，但对 TypeScript 语法（比如接口、泛型）或 @type 中的复杂类型表达式，需要明确告诉它“后面有 TS 信息”。否则 @param 能识别，@type 里的类型结构会被忽略，导致文档中类型显示为 any 或空。
关键配置在 apidoc.json 中：
{
"input": ["src"],
"output": "docs",
"typescript": {
"enabled": true,
"tsconfig": "./tsconfig.json"
}
}
- 必须指定
tsconfig路径，否则 apidoc 不知道该用哪套规则解析@type - 如果项目用 ESM（
type: "module"），确保tsconfig.json中module设置为"ESNext"或"NodeNext"，否则 apidoc 解析时可能报模块解析失败 - 注意：apidoc 不处理
.d.ts文件，所有类型信息必须来自 JS 文件内的 JSDoc，所以不要指望把类型定义全挪到声明文件里再让 apidoc 自动读取
生产环境真正起效的两个隐藏前提
很多团队以为配完就万事大吉，结果上线后依然出现类型相关 runtime error。问题往往出在这两点：
- CI/CD 流水线里没运行
tsc --noEmit做类型检查：光靠编辑器提示不够，必须在构建阶段强制校验，否则开发机上看着 OK，合并后可能因分支差异失效 - 没有把
jsdoc注释和@type当作代码契约来维护：比如 API 返回字段变了，只改了实现，忘了更新/** @returns {Promise} */，文档和类型检查就立刻脱节
最简验证方式：在 CI 中加一行 npx tsc --noEmit --jsx react-jsx，失败即阻断发布。类型不是装饰，是生产环境里第一道自动化的契约校验。
