VS Code 默认可能禁用严格空值检查，导致 JSDoc 中如 LinkedListNode | null 的联合类型在悬停时仅显示 LinkedListNode，本文详解如何通过配置 jsconfig.json 或 VS Code 设置启用 strictNullChecks 以正确显示完整类型。
vs code 默认可能禁用严格空值检查，导致 jsdoc 中如 `linkedlistnode | null` 的联合类型在悬停时仅显示 `linkedlistnode`，本文详解如何通过配置 `jsconfig.json` 或 vs code 设置启用 `strictnullchecks` 以正确显示完整类型。
在 JavaScript 项目中使用 JSDoc 进行类型标注（如 /** @type {LinkedListNode | null} */）时，VS Code 的智能提示应如实反映联合类型。但实践中常遇到悬停提示丢失 null（或 undefined）的情况——例如本例中 this.next 仅显示为 LinkedListNode，而非预期的 LinkedListNode | null。这并非 JSDoc 语法错误，而是 TypeScript 类型检查器的空值处理策略未生效所致。
根本原因：strictNullChecks 未启用
VS Code 内置的 JavaScript 类型检查基于 TypeScript 编译器，其行为受 strictNullChecks 控制。该选项决定是否将 null 和 undefined 视为独立类型（启用后，T | null 不会自动收缩为 T）。关键点在于：
-
jsconfig.json中的"strict": true会间接启用strictNullChecks，但直接显式配置更可靠； - 更易被忽略的是 VS Code 的隐式项目配置（
js/ts.implicitProjectConfig.*），其中js/ts.implicitProjectConfig.strictNullChecks默认为true——若被手动设为false，将覆盖所有显式配置。
解决方案：双路径验证与配置
✅ 方案一：显式配置 jsconfig.json（推荐）
在项目根目录创建或更新 jsconfig.json，明确启用 strictNullChecks：
{
"compilerOptions": {
"strictNullChecks": true,
"allowJs": true,
"checkJs": true,
"target": "ES2020",
"module": "commonjs"
},
"include": ["**/*.js"],
"exclude": ["node_modules"]
}
⚠️ 注意：
"strict": true虽可启用strictNullChecks，但为避免隐式依赖，建议直接设置"strictNullChecks": true。
✅ 方案二：检查 VS Code 隐式设置
打开 VS Code 设置（Ctrl+, / Cmd+,），搜索：js/ts.implicitProjectConfig.strictNullChecks
确保其值为 true（默认即如此，但可能被误改）。若为 false，请切换回 true 并重启 VS Code 窗口（Developer: Reload Window）。
✅ 验证 JSDoc 语法（次要但必要）
确保类型标注符合规范（以下写法均有效）：
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
/** @type {LinkedListNode | null} */ // ✅ 推荐：清晰直观
/** @type {?LinkedListNode} */ // ✅ 支持，但语义稍弱
/** @type {(LinkedListNode|null)} */ // ✅ 括号无影响
同时，constructor 参数的 JSDoc（如 @param {LinkedListNode | undefined} next）需与 @type 声明逻辑一致，避免类型推断冲突。
效果验证
配置生效后，悬停 this.next 将正确显示：
(property) LinkedListNode.next: LinkedListNode | null
且对 null 的访问（如 node.next?.value）会获得准确的可选链提示，if (node.next) 等守卫条件也能被类型系统识别。
总结
JSDoc 联合类型不显示 null 的本质是 TypeScript 类型检查的 strictNullChecks 开关未开启。优先通过 jsconfig.json 显式启用该选项，并排查 VS Code 隐式设置是否被意外关闭。配置后无需修改代码逻辑，即可获得精准的类型提示，大幅提升 JavaScript 项目的类型安全性和开发体验。
