TypeScript + JSDoc 实现类型安全与文档化

本文深入解析了如何通过 TypeScript 与 JSDoc 的协同使用，在纯 JavaScript 项目中实现真正的类型安全与自动化文档生成：关键在于正确配置 `tsconfig.json`（必须同时启用 `allowJs` 和 `checkJs`，配合 `strict: false` 渐进迁移、`skipLibCheck: true` 加速构建），精准运用 `@type {import('./types').Config}` 等 JSDoc 类型引用语法替代 TS 声明，确保 apidoc 在 `typescript.enabled: true` 且指定有效 `tsconfig` 的前提下准确解析复杂类型，并强调类型检查必须落地到 CI/CD 阶段（如 `tsc --noEmit`）和日常开发契约中——因为类型不是编辑器的装饰，而是生产环境里沉默却不可绕过的第一道质量防线。

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 };

正确写法（显式引用 + 内联类型）：

/** @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<{ id: number, name: string }>} */，文档和类型检查就立刻脱节

最简验证方式：在 CI 中加一行 npx tsc --noEmit --jsx react-jsx，失败即阻断发布。类型不是装饰，是生产环境里第一道自动化的契约校验。

到这里，我们也就讲完了《TypeScript + JSDoc 实现类型安全与文档化》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！