JavaScript / TypeScript / 系统课时

检查 JavaScript 文件

检查 JavaScript 文件

本课解决“旧代码暂时不能全部改成 TypeScript,但希望立即获得类型检查”的问题。你将通过 allowJs、checkJs 和 JSDoc,让 .js 文件进入 TypeScript 的检查范围,并学会控制检查粒度与处理遗留例外。

学习目标

  • 为整个项目或单个 JavaScript 文件启用类型检查
  • 使用 JSDoc 描述参数、返回值和对象结构
  • 根据编译错误修复类型问题,并控制临时豁免范围

启用 JavaScript 检查

项目级检查适合已经准备统一治理的代码库。allowJs 允许 TypeScript 项目包含 .js 文件,checkJs 让这些文件产生类型错误,noEmit 表示只检查、不接管原有构建产物。

json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": true
  },
  "include": ["src/**/*.js"]
}

保存为项目根目录的 tsconfig.json 后,src 下的 JavaScript 文件会参与检查。若只想试点单个文件,可保持 checkJs 为 false,并在目标文件第一行添加 // @ts-check;暂不处理的文件可使用 // @ts-nocheck,但应记录清理计划。

用 JSDoc 补充类型

JavaScript 没有 TypeScript 的类型标注语法,检查器会优先使用代码推断,再读取 JSDoc。下面的完整示例定义了商品结构、函数参数和返回值,并故意传入错误类型以验证检查是否生效。

js
// src/price.js

/**
 * @typedef {{ name: string, unitPrice: number }} Product
 */

/**
 * 计算指定数量商品的小计。
 * @param {Product} product
 * @param {number} quantity
 * @returns {number}
 */
function subtotal(product, quantity) {
  if (quantity <= 0) {
    return 0;
  }
  return product.unitPrice * quantity;
}

const item = { name: "Keyboard", unitPrice: 299 };
console.log(subtotal(item, "2"));

@typedef 适合复用对象结构,@param 约束输入,@returns 明确输出。不要为了消除报错把所有类型都写成 any;无法立即确认的数据更适合先标为 unknown,在使用前完成判断。

运行检查并读取错误

在安装了 TypeScript 的项目中执行:

bash
npx tsc -p tsconfig.json

预期输出:

text
src/price.js(<LINE>,<COLUMN>): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

<LINE> 和 <COLUMN> 会随文件内容变化。将调用中的 "2" 改为数字 2 后再次执行,预期结果为:

text
无错误输出,进程退出码为 0。

由于配置了 noEmit,检查成功不会生成新的 JavaScript 文件,也不会改变原项目的打包流程。

控制检查范围与临时例外

迁移初期应从稳定目录或高风险模块开始,而不是一次把所有遗留文件都纳入检查。include 和 exclude 用于控制文件集合,文件顶部的 @ts-check 用于小范围试点。

确实无法立即修复某一行时,可以在它前面使用 // @ts-expect-error。它会在错误消失后提醒你删除豁免,比长期使用 // @ts-ignore 更容易治理。整文件关闭检查的 @ts-nocheck 只适合生成代码、暂不可维护代码或明确登记的过渡文件。

常见问题

JavaScript 的推断规则比 TypeScript 文件更宽松。例如,动态添加属性、缺少参数或以 null 初始化变量时,结果可能不够精确。遇到此类情况,应优先补充 JSDoc、收紧对象结构或在入口处校验数据,而不是依赖断言掩盖真实风险。

第三方库缺少类型时,先安装对应的类型声明包;若没有可用声明,可为关键 API 编写最小 .d.ts 文件。声明只描述你实际调用的接口,避免一次性虚构整个库的类型。

本课总结

  • allowJs 负责纳入 JavaScript 文件,checkJs 或 @ts-check 负责启用错误检查
  • JSDoc 可以在不改写 .js 文件的前提下补充可复用类型信息
  • 应用最小范围豁免,并通过 tsc --noEmit 持续验证检查结果

下一课预告

下一课将把检查能力扩展为渐进迁移流程,按模块逐步改写旧项目,并集中处理隐式 any、空值和第三方类型依赖。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

检查 JavaScript 文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通