升级Angular等依赖后TypeScript编译配置警告的解决求助

背景 #

通过以下命令完成前端依赖升级：

ncu -u
npm install --legacy-peer-deps

升级的核心依赖版本：

typescript 4.8.4   -> 5.0.4
Angular    14      -> 16
Node       16.13.2 -> 18.16.0
npm        8.x.x   -> 9.6.6
NgRx       14      -> 16（可能无关）
RxJs       7.5.x   -> 7.8.x（可能无关）

启动项目后触发警告：

TypeScript compiler options "target" and "useDefineForClassFields" are set to "ES2022" and "false" respectively by the Angular CLI. To control ECMA version and features use the Browerslist configuration.
NOTE: You can set the "target" to "ES2022" in the project's tsconfig to remove this warning.

当前项目tsconfig.json中target为ES2015，直接改为ES2022会导致应用加载失败，影响整个前端栈，因此需要其他方式消除警告。

当前tsconfig.json配置如下：

{
    "compileOnSave": true,
    "angularCompilerOptions": {
        "fullTemplateTypeCheck": true,
        "preserveWhitespaces": true,
        "strictInjectionParameters": true,
        "disableTypeScriptVersionCheck": true,
        "enableIvy": true
    },
    "compilerOptions": {
        "baseUrl": "src",
        "declaration": false,
        "downlevelIteration": true,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "importHelpers": true,
        "mapRoot": "./",
        "outDir": "./dist",
        "sourceMap": true,
        "removeComments": false,
        "noImplicitAny": false,
        "moduleResolution": "node",
        "module": "ESNext",
        "target": "ES2015",
        "lib": [
            "dom"
        ],
        "paths": {
            "ctm-common": [
                "app/+common"
            ],
            "ctm-shared": [
                "app/+shared"
            ],
            "ctm-store": [
                "app/+store"
            ],
            "ctm-store/*": [
                "app/+store/*"
            ]
        },
        "types": [
            "jasmine",
            "node",
            "gsap"
        ],
        "typeRoots": [
            "./node_modules/@types",
            "./node_modules/rxjs/symbol",
            "./node_modules/angular-split"
        ]
    },
    "files": [
        "src/app/app.module.ts",
        "src/app/admin/admin.module.ts",
        "src/app/portal/portal.module.ts",
        "src/app/portfolios/portfolios.module.ts",
        "src/app/navigate/navigate.module.ts",
        "src/app/visuals/visuals.module.ts",
        "src/app/users/user-report.module.ts",
        "src/app/promoter/promoter.module.ts",
        "src/app/diagnostics/diagnostic.module.ts",
        "src/main.ts",
        "src/polyfills.ts"
    ],
    "include": [
        "./node_modules/angular-split/angular-split.d.ts",
        "./node_modules/ngx-clipboard/*/**.ts",
        "./node_modules/gsap/*"
    ],
    "exclude": [
        "test.ts",
        "**/*.spec.ts"
    ]
}

解决方案 #

1. 显式对齐CLI默认配置快速消警 #

在tsconfig.json的compilerOptions中添加useDefineForClassFields: false，保留target: ES2015，让本地配置和Angular CLI的默认覆盖值对齐，直接消除警告：

"compilerOptions": {
    // ... 其他原有配置
    "target": "ES2015",
    "useDefineForClassFields": false,
    // ... 其他原有配置
}

2. 用Browserslist统一管理兼容性（推荐长期方案） #

Angular 16开始推荐通过Browserslist替代手动设置target来控制编译的ECMA版本。确保项目根目录有browserslist配置文件，内容对应你需要兼容的浏览器范围，例如：

> 0.5%
last 2 versions
Firefox ESR
not dead
IE 11 // 若需兼容IE11则保留

配置完成后，Angular CLI会自动根据浏览器列表确定合适的编译目标，此时即使tsconfig中保留target: ES2015，警告也会被自动忽略。

3. 强制CLI使用指定编译目标 #

在angular.json的projects.[你的项目名称].architect.build.options中添加target配置，覆盖CLI默认的ES2022设置，让编译目标与tsconfig保持一致：

"options": {
    // ... 其他原有配置
    "target": "ES2015"
}

4. 排查ES2022切换失败的根因（可选） #

如果尝试切换target到ES2022时出现加载失败，可检查src/polyfills.ts，确保适配Angular 16的polyfills已正确引入，比如core-js相关模块：

import 'core-js/es/array';
import 'core-js/es/object';
// 根据项目需求补充其他polyfills

关键说明 #

Angular 16对TypeScript编译逻辑做了调整：CLI默认会强制设置target: ES2022和useDefineForClassFields: false，目的是引导开发者通过Browserslist统一管理浏览器兼容性，而非手动修改tsconfig的target字段。当本地tsconfig的target与CLI默认值冲突时，就会触发该警告。

上述方案中，方案1是快速消警的临时方案；方案2符合Angular官方推荐的长期实践；方案3适合需要严格控制编译输出的场景。

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