Javascript

TL;DR 小而快、少改造 → 用 JSDoc：零编译、成本低，智能提示+基本类型检查够用。 多人协作、复杂模型、长期演进 → 上 TypeScript：强约束、类型表达力强、生态支持完整。 还不确定？先用 JSDoc“铺轨”，4 周后复盘：若出现类型灰区/重构痛点，再切 TS。 两条路线各自的价值 JSDoc（纯 JS + 注释） ✅ 零构建成本：不改语法，直接运行。 ✅ 渐进引入：从公共 API 开始补，风险低。 ✅ 编辑器体验好：配合 checkJs、@types/* 即可。 ⚠️ 约束力弱：注释易缺失，无法“强制全覆盖”。 ⚠️ 复杂类型表达受限：高级泛型/条件/映射类型较难。 最适合：中小型服务、内部应用、追求快和轻、不想上编译链的项目。 TypeScript（.ts 编译） ✅ 强约束：类型写进语法，覆盖更彻底。 ✅ 表达力强：条件/映射/模板字面量等高级类型。 ✅ 生态一等支持：工具链、生成 .d.ts、SDK/库发布友好。 ⚠️ 需要编译：构建链与 CI 复杂度提升。 ⚠️ 渐进成本：历史代码迁移需要计划与时间。 最适合：多人协作、复杂领域模型、公共库/SDK、长期维护和频繁重构的项目。 适用场景对比（速查表） 维度 JSDoc TypeScript 上手/改造成本 低 中-高 类型严格度 中 高（可设 strict） 复杂类型建模 限制较多 很强 团队协作/重构 基本满足 最佳 发布库/SDK 勉强可行 一等公民 运行/构建复杂度 低 中-高 演进与长远性 中 高 决策树（按“是/否”走） 是否需要强约束（类型缺失视为错误）？ 是 → 倾向 TS；否 → 2 是否存在复杂领域模型/广泛复用的内部包？ 是 → TS；否 → 3 是否强烈希望零编译、保留纯 JS 运行链路？ 是 → JSDoc；否 → 4 团队对 TS 是否有经验/意愿维护构建？ 有 → TS；无 → 先 JSDoc，后评估升级 最小可用配置（落地模板） 路线 A：JSDoc（纯 JS） jsconfig.json { "compilerOptions": { "checkJs": true, "lib": ["ES2022"], "moduleResolution": "node", "types": ["node", "express"] }, "include": ["src/**/*.js"], "exclude": ["dist", "node_modules"] } 安装类型声明（开发依赖）： npm i -D @types/node @types/express 在关键文件顶部可加： // @ts-check 给公共 API/中间件/配置对象补 JSDoc（从“对外接口”开始，收益最大）。 路线 B：TypeScript（增量迁移） tsconfig.json（最小严格模式） { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "outDir": "dist" }, "include": ["src"] } 增量迁移策略： 第 1 周：保留 JS 运行，新增 TS 构建（Babel/tsc 任一）。 第 2–3 周：核心域模型与公共模块改为 .ts。 第 4 周：把“边缘模块”迁移/隔离，补充 .d.ts 输出和 CI 阶段类型检查。 选型建议清单（给 Express 团队） 满足即可：内部服务、接口清晰、少人维护 → JSDoc。 追求稳健：多人、多模块、频繁重构、长期维护 → TS。 灰度策略：JSDoc 起步，记录“类型痛点”，当痛点达到阈值（如 3 次以上重构失误/PR 反复）→ 立项迁移 TS。 常见反模式与规避 JSDoc 只写几处：缺少全局 checkJs 或关键路径无注释 → 约束形同虚设。 编辑器与运行时别名不一致：jsconfig.paths 生效但 Node 不认；ESM 下用 package.json#imports 对齐。 TS 一上来全量重写：风险高、节奏乱；应优先迁移“被多处依赖的核心模块”。 TS 关掉严格模式：失去大量价值；若负担大，先放开个别规则而非整体关闭。 实操建议（一句话版） 能用 JSDoc 先解决 80% 问题就用 JSDoc；当复杂度与团队协作要求上来，再切 TypeScript。 把“是否迁移 TS”变成数据驱动的决策：统计类型相关故障/重构回滚次数、PR 讨论成本作为阈值。 需要的话，把你项目的目录结构与典型模块贴给我，我可以根据现状给出“JSDoc 够用 or 值得上 TS”的个性化建议与实施计划。 ...

jsconfig 配置的作用 在某个目录放一个 jsconfig.json，VS Code 就把它当作JavaScript 项目根。文件里定义项目包含的源文件与语言服务选项，从而影响智能提示、自动导入、转到定义、错误检查等编辑器体验。(Visual Studio Code) VS Code 没有 jsconfig 也能工作，但当你的工作区里并非所有 JS 文件都属于同一个项目，或需要路径别名/包含范围等配置时，就应该创建它。(Visual Studio Code) 它本质上是 tsconfig.json 的“JS 版变体”，只作用于编辑器的 JS/JSX 语言服务（不参与打包）。(Visual Studio Code) 为什么/什么时候需要 VS Code JS 支持有两种模式： File Scope（无 jsconfig）：每个文件独立，没有统一的项目上下文。 Explicit Project（有 jsconfig）：用 jsconfig.json 明确项目边界与解析规则。 当你需要更准确的 IntelliSense、跨文件跳转、非相对导入/别名，建议使用 jsconfig。(GitHub) 常用配置项（高频） include / exclude：工程边界。只把 src/ 等需要的目录纳入项目。(Visual Studio Code) compilerOptions.baseUrl + paths：配置路径别名（如 @/），让 VS Code 能解析到定义并提供自动导入。(Visual Studio Code) checkJs：对 .js/.jsx 做 TS 级别类型检查（配合 JSDoc 与 .d.ts）以发现更多类型错误。(Visual Studio Code) jsx：设置 JSX 处理方式（如 React 17+ 的 react-jsx）。(Visual Studio Code) 其他常见：module、moduleResolution、resolveJsonModule、types 等，影响编辑器如何解析模块与可见的全局类型（例如 Node/React）。(Visual Studio Code) 小技巧：用命令面板 JavaScript: Go to Project Configuration 可检查当前文件是否被某个 jsconfig.json 管理。(Visual Studio Code) ...