执行Gulp编译TypeScript源码时报TS1005 ';' expected错误

错误现象 #

VS2022开发环境下应用可正常运行，执行Gulp任务编译TypeScript源码时触发TS1005错误，错误信息如下：

C:/WebProjects/ITF/Web/node_modules/typescript/lib/lib.es6.d.ts(20624,14): error TS1005: ';' expected.
C:/WebProjects/ITF/Web/node_modules/typescript/lib/lib.es6.d.ts(20625,14): error TS1005: ';' expected.
C:/WebProjects/ITF/Web/node_modules/typescript/lib/lib.es6.d.ts(20626,14): error TS1005: ';' expected.

现有配置与代码 #

Gulp编译任务代码 #

gulp.task("compile", gulp.series("clean", function () {
    const stream = gulp.src("./App/**/*.ts")
        .pipe(inlineNg2Template({
            base: "/",                  // Angular2 application base folder
            target: "es6",              // Can swap to es5
            indent: 2,                  // Indentation (spaces)
            useRelativePaths: false,     // Use components relative assset paths
            removeLineBreaks: false,     // Content will be included as one line
            templateExtension: ".html", // Update according to your file extension
            templateFunction: false    // If using a function instead of a string for `templateUrl`, pass a reference to that function here
        }))
        .pipe(typescript(tsProject))
        .pipe(ignore("References.js"))
        .pipe(gulp.dest("dist/App"));
    return stream;
}));

tsconfig.json配置 #

{
  "compilerOptions": {
    "target": "es5",
    "module": "amd",
    "moduleResolution": "node",
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "noEmitHelpers": false,
    "sourceMap": true,
    "noResolve": false,
    "noEmitOnError": true,
    "outDir": "dist/debug"
  },
  "filesGlob": [
    "./**/*.ts",
    "!./node_modules"
  ],
  "exclude": [
    "node_modules",
    "jspm_packages",
    "typings",
    "dist",
    "typings/*",
    "typings/main.d.ts",
    "typings/main",
    "Scripts"
  ],
  "compileOnSave": true,
  "buildOnSave": true
}

package.json依赖配置 #

"dependencies": {
  "@angular/cli": "^6.2.1",
  "@angular/common": "4.4.7",
  "@angular/compiler": "4.4.7",
  "@angular/core": "4.4.7",
  "@angular/forms": "4.4.7",
  "@angular/http": "4.4.7",
  "@angular/platform-browser": "4.4.7",
  "@angular/platform-browser-dynamic": "4.4.7",
  "@angular/router": "4.4.7",
  "@angular/upgrade": "4.4.7",
  "a": "^2.1.2",
  "angular-in-memory-web-api": "0.2.5",
  "core-js": "^2.4.1",
  "debug": "^4.1.1",
  "gulp": "^4.0.2",
  "gulp-cli": "^2.3.0",
  "gulp-typedoc": "^1.2.1",
  "gulp4-run-sequence": "^1.0.1",
  "moment": "2.17.1",
  "reflect-metadata": "^0.1.8",
  "rxjs": "5.4.3",
  "systemjs": "0.19.39",
  "zone.js": "^0.8.4"
},
"devDependencies": {
  "gulp-comment-swap": "0.0.10",
  "gulp-concat": "^2.6.0",
  "gulp-htmlclean": "^2.7.22",
  "gulp-ignore": "^2.0.1",
  "gulp-inject": "^5.0.5",
  "gulp-inline-ng2-template": "^5.0.1",
  "gulp-insert": "^0.5.0",
  "gulp-jspm": "^0.5.13",
  "gulp-rename": "^1.2.2",
  "gulp-replace": "^0.5.4",
  "gulp-rimraf": "^0.2.0",
  "gulp-shell": "^0.8.0",
  "gulp-sourcemaps": "^1.6.0",
  "gulp-tslint": "^8.1.4",
  "gulp-tslint-stylish": "^1.1.1",
  "gulp-typescript": "^2.13.0",
  "gulp-uglify": "^3.0.2",
  "gulp-util": "^3.0.2",
  "gulp-watch": "^4.0.1",
  "highcharts": "^10.0.0",
  "html-loader": "^0.4.0",
  "immutable": "^3.8.1",
  "install": "^0.4.1",
  "json-loader": "^0.5.3",
  "moment": "^2.29.2",
  "npm": "^8.6.0",
  "redux": "^3.5.2",
  "rimraf": "^2.4.4",
  "run-sequence": "^1.1.5",
  "superstatic": "^7.1.0",
  "ts-loader": "^0.7.2",
  "tsc": "^1.20150623.0",
  "tsconfig-lint": "^0.12.0",
  "tslint": "^3.2.1",
  "tslint-loader": "^2.1.0",
  "typedoc": "^0.2.2",
  "typescript": "2.7.2",
  "typings": "^1.3.2"
}

根因分析 #

• 核心问题是gulp-typescript版本过低：当前安装的gulp-typescript@2.13.0为2016年发布的老旧版本，内置的TypeScript语法解析器最高仅支持TS2.0及以下语法，无法识别本地安装的TypeScript2.7自带的lib.es6.d.ts中新增的ES2015+类型声明语法，解析到新语法时直接抛出缺分号的TS1005错误。VS2022编译时调用的是IDE集成的高版本TS编译器，因此应用可正常运行。
• 配置存在冲突：Gulp任务中inlineNg2Template的target参数设为es6，但tsconfig.json中配置的编译目标为es5，二者不匹配会导致内联模板生成的代码语法与后续TS编译预期不符。
• 老版本gulp-typescript对tsconfig.json的exclude字段识别存在缺陷，未正确过滤node_modules目录下的声明文件，导致内置库的d.ts文件被纳入编译流程触发报错。

修复步骤 #

• 升级gulp-typescript到适配TypeScript2.7的版本，执行命令：npm install gulp-typescript@4.0.2 --save-dev。4.x版本的gulp-typescript会直接调用项目本地安装的typescript包完成编译，不再使用内置的老旧解析器。
• 修正inlineNg2Template配置，将target字段的值从es6改为es5，和tsconfig.json的编译目标保持一致。
• 显式配置tsProject的排除规则，规避老版本对exclude字段识别不全的问题，创建tsProject的代码修改为：

const tsProject = typescript.createProject('tsconfig.json', {
  exclude: ['node_modules/**', 'dist/**', 'typings/**', 'Scripts/**', 'jspm_packages/**']
});

• 清理缓存重新安装依赖：删除项目下的node_modules目录和package-lock.json文件，重新执行npm install，避免多版本TypeScript共存引发的冲突。
• 重新执行gulp compile任务验证编译结果，原有lib.es6.d.ts相关的TS1005错误会消失。

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