JavaScript / TypeScript / 系统课时
检查 JavaScript 文件
检查 JavaScript 文件
本课解决“旧代码暂时不能全部改成 TypeScript,但希望立即获得类型检查”的问题。你将通过 allowJs、checkJs 和 JSDoc,让 .js 文件进入 TypeScript 的检查范围,并学会控制检查粒度与处理遗留例外。
学习目标
- 为整个项目或单个 JavaScript 文件启用类型检查
- 使用 JSDoc 描述参数、返回值和对象结构
- 根据编译错误修复类型问题,并控制临时豁免范围
启用 JavaScript 检查
项目级检查适合已经准备统一治理的代码库。allowJs 允许 TypeScript 项目包含 .js 文件,checkJs 让这些文件产生类型错误,noEmit 表示只检查、不接管原有构建产物。
{
"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。下面的完整示例定义了商品结构、函数参数和返回值,并故意传入错误类型以验证检查是否生效。
// 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 的项目中执行:
npx tsc -p tsconfig.json预期输出:
src/price.js(<LINE>,<COLUMN>): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.<LINE> 和 <COLUMN> 会随文件内容变化。将调用中的 "2" 改为数字 2 后再次执行,预期结果为:
无错误输出,进程退出码为 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、空值和第三方类型依赖。