使用第三方JS库Recurly JS的TS类型时出现TS2307编译错误怎么解决？

根因分析 #

你遇到的报错分两类：

1. TS2307找不到模块是因为Gulp的TS编译配置错误，且gulp.src未包含对应类型声明文件
2. 其余第三方类型包的语法错误是老项目TS版本与新版Recurly类型包不兼容导致

第一步：修复Gulp编译配置 #

你当前的Gulp任务写法存在逻辑错误：已经调用typescript.createProject读取tsconfig配置，后续又直接给typescript()传自定义配置，相当于完全覆盖了tsconfig的规则，而且gulp.src仅匹配了业务代码文件，未包含类型声明文件。替换为以下配置：

gulp.task('ts:compile', function (callback) {
    // 将自定义配置和tsconfig合并，避免覆盖
    var project = typescript.createProject('tsconfig.json', {
        noImplicitAny: true,
        target: 'es5',
        removeComments: true
    });
    pump([
        gulp.src(
            [
                jsPath + 'Models/*.ts',
                jsPath + '*.ts',
                // 显式引入Recurly类型文件
                './node_modules/@types/recurly__recurly-js/**/*.d.ts'
            ]
            ),
        // 用createProject生成的编译实例，不要重新传配置
        project(),
        gulp.dest(compiledJsPath)
    ], callback);
});

第二步：修复类型包兼容性问题 #

在tsconfig.json的compilerOptions中添加以下配置，跳过第三方类型校验、补充缺失的标准类型：

{
  "compilerOptions": {
    "moduleResolution": "node",
    "skipLibCheck": true,
    "lib": ["es5", "es2015.promise", "dom"],
    "typeRoots": ["./node_modules/@types"]
  }
}

如果老项目TS版本低于4.0无法适配新版类型包，可以安装兼容旧TS的历史版本：
npm install --save @types/recurly__recurly-js@4.0.2

快速兜底方案 #

如果需要临时快速解决问题上线，可以不依赖官方类型包，自己补充类型声明：

1. 在TS源码目录新建globals.d.ts文件，添加以下内容：

declare module '@recurly/recurly-js' {
  // 可以按需声明你用到的类型，也可以直接设为any
  export interface Address {
    address1: string;
    address2?: string;
    city: string;
    postal_code: string;
    country: string;
    // 其他用到的字段自行补充
  }
}

2. 如果Recurly是通过script标签全局引入的，直接在用到的文件顶部加declare var recurly: any;即可跳过所有类型校验。

内容的提问来源于stack exchange，提问作者omatase