Angular `inject` 函数迁移（inject-migration）完全指南：从构造函数注入到 `inject()` 的自动化改造

2026-09-07 19:35:48作者：姚月梅Lane

在 Angular 的依赖注入（DI）实践中，inject 函数相比传统基于构造函数的注入，能够提供更精确的类型推导，并且与标准装饰器体系（如 Signal 等新特性）拥有更好的兼容性。本文围绕官方迁移指南 adev/src/content/reference/migrations/inject-function.md，结合当前仓库中 inject-migration 的实现源码，完整讲解如何通过一条 Schematic 命令将类中的构造函数注入批量改写为 inject() 函数式注入，深入剖析四个迁移选项的取舍逻辑，并辅以源码级证据说明迁移在"何时迁移、哪些不动、类型如何处理"背后的判定规则。读完本文，你可以安全地在自己的 Angular 项目中运行该迁移，并在遇到边界情况时知道如何通过选项进行控制。

为什么要把构造函数注入迁移到 `inject()` 函数

在 Angular 的传统写法中，依赖通常在类构造函数中以参数形式注入：

import {Component, Inject, Optional} from '@angular/core';
import {MyService} from './service';
import {DI_TOKEN} from './token';

@Component()
export class MyComp {
  constructor(
    private service: MyService,
    @Inject(DI_TOKEN) @Optional() readonly token: string,
  ) {}
}

这种写法存在两点结构性局限：

类型精度不足：装饰器（如 @Optional、@Inject）无法参与 TypeScript 的类型推导。例如 @Optional() 参数在注入失败时运行时返回 null，但标注类型无法自动带上 | null，导致大量存量代码的类型其实并不准确；
与装饰器体系的兼容性问题：随着 Angular 迈向更标准的装饰器与响应式 API 生态，基于函数调用的 inject() 在设计上更贴合这一趋势。

从仓库实现看，官方将 inject() 描述为更优的注入入口：它的返回类型直接反映注入结果（可选注入会推导为 T | null），类型系统因此更真实。同时，inject() 作为普通函数，可以在类字段初始化器、甚至组件外部的工具函数中调用，摆脱了对构造函数声明位置的束缚。

使用 inject() 改写后的类如下：

import {Component, inject} from '@angular/core';
import {MyService} from './service';
import {DI_TOKEN} from './token';

@Component()
export class MyComp {
  private service = inject(MyService);
  readonly token = inject(DI_TOKEN, {optional: true});
}

字段从构造函数参数中释放出来，直接在类体内完成声明与赋值：非可选依赖直接调用 inject(MyService)；可选依赖通过第二个参数对象 {optional: true} 表达，其推导类型即为 string | null。

运行迁移：命令与注册方式

迁移以 Angular Schematic 形式提供，命令为：

ng generate @angular/core:inject

在 collection.json 中可以看到该 Schematic 的注册信息：

"inject-migration": {
  "description": "Converts usages of constructor-based injection to the inject() function",
  "factory": "./bundles/inject-migration.cjs#migrate",
  "schema": "./ng-generate/inject-migration/schema.json",
  "aliases": ["inject"]
}

由此可知几点细节：

Schematic 内部完整名称为 inject-migration，对外暴露的 alias 是 inject，因此 ng generate @angular/core:inject 与 ng generate @angular/core:inject-migration 等价；
其选项 Schema 位于 schema.json；
迁移核心逻辑位于 migration.ts，入口编排位于 index.ts。

从 index.ts 的入口实现（migrate 函数）可以还原迁移的执行链路：

通过 getProjectTsConfigPaths 收集项目中所有 build 与 test 的 tsconfig 路径（buildPaths + testPaths）。如果找不到任何 tsconfig，会打印警告 Could not find any tsconfig file. Cannot run the inject migration. 并直接返回；
针对每个 tsconfig 构建 TypeScript 迁移程序（createMigrationProgram），并以文件级路径过滤加 canMigrateFile 判定选择待迁移文件；
对每个源文件调用 migrateFile 生成文本变更（删除与插入），通过 Tree 的 beginUpdate/commitUpdate 写回磁盘；
如果最终没有任何文件发生变更，会打印 Inject migration did not find any files to migrate 提示。

该实现还内建了路径安全校验：如果 options.path 以 .. 开头，会直接抛出 Cannot run inject migration outside of the current project.，禁止迁移范围逃逸出当前项目目录。

迁移判定：哪些类会被改写

迁移并非盲目替换所有构造函数。在 analysis.ts 中，analyzeFile 通过一组判定规则决定候选类：

带 DI 装饰器：只有带有 Component、Directive、Pipe、NgModule、Injectable 这五类装饰器（常量 DECORATORS_SUPPORTING_DI）的类才会被纳入迁移范围；
存在带参数的构造函数体：构造函数必须存在函数体（body != null）且参数数量大于 0；
参数可注入性初筛：代码只做"基本检查"而非穷举（注释明确说明 exhaustive 检查需要完整类型检查器）。它把 true/false/number/string/null/void 等字面量类型关键字视为不可注入类型（常量 UNINJECTABLE_TYPE_KINDS），除非这些参数带有 Inject 或 Attribute 装饰器；
抽象类默认跳过：见下文 migrateAbstractClasses 选项；
DI 相关符号识别：迁移关注 Inject、Attribute、Optional、SkipSelf、Self、Host、forwardRef 等参数装饰器/符号（常量 DI_PARAM_SYMBOLS）。

此外，分析阶段会统计 @angular/core 中 DI 符号在文件内的"非装饰器引用"次数（nonDecoratorReferences），用于判断清理导入语句时是否需要保留。例如某个 Inject 符号除了做参数装饰器外还被业务代码直接引用，导入就不能被贸然删除。

迁移选项详解

迁移共提供四个配置项，通过 CLI 交互式询问或直接传参控制。各选项的默认值与含义在 schema.json 中有明确定义（path 默认 ./，其余布尔项默认均为 false）。

`path`

指定要迁移的项目子路径：

ng generate @angular/core:inject --path=./src/app/feature

传入 . 或留空表示迁移整个目录（Schema 默认值为 ./）；
从 index.ts 看，该路径会与 process.cwd() 拼接后作为文件前缀过滤条件（sourceFile.fileName.startsWith(pathToMigrate)）；
不允许指向项目外部（以 .. 开头的路径直接抛异常）。

如果你的仓库很大，希望分批次、按模块逐步迁移并逐段回归验证，该参数是最主要的作用域控制手段。

`migrateAbstractClasses`

ng generate @angular/core:inject --migrateAbstractClasses=true

Angular 不会校验抽象类构造参数的可注入性——抽象类本身无法被实例化，编译器不会为它做 DI 参数解析。这意味着迁移无法可靠地把抽象类的构造参数改写为 inject()（字段初始化器在实例化子类时才执行，无法保证参数一定可注入），因此默认不迁移抽象类。

从 analysis.ts 的判定可见：

(!isAbstract || options.migrateAbstractClasses)

只有当该选项为 true 时，抽象类（带 abstract 修饰符且支持 DI）才会进入候选队列。官方文档明确提醒：开启后可能需要手工修复若干破坏，请务必为这类改动补充回归测试。

`backwardsCompatibleConstructors`

默认情况下，迁移会尽量把代码"打扫干净"——包括删除构造函数中不再需要的参数，甚至当构造函数不再包含任何代码时将其整体删除。但存在一个已知的破坏场景：当带 Angular 装饰器的类继承自另一个带 Angular 装饰器的类时，若父类构造函数签名被改变/移除，子类的 super(...) 调用可能出现编译错误。

启用该选项后，迁移会额外生成一个重载签名以保持向后兼容，代价是产生更多代码。

ng generate @angular/core:inject --backwardsCompatibleConstructors=true

转换前后对照：

// Before
import {Component} from '@angular/core';
import {MyService} from './service';

@Component()
export class MyComp {
  constructor(private service: MyService) {}
}

// After
import { Component } from '@angular/core';
import { MyService } from './service';

@Component()
export class MyComp {
  private service = inject(MyService);

  /*_ Inserted by Angular inject() migration for backwards compatibility _*/
  constructor(...args: unknown[]);

  constructor() {}
}

注意生成的是一个构造签名重载 constructor(...args: unknown[]) 加实际空实现 constructor() {}：前者让任何可能的 super(...) 调用在类型层面保持合法，后者保证运行时无需处理参数。

关于参数与构造函数删除逻辑，analysis.ts 还提供了底层支撑函数：

getConstructorUnusedParameters：识别构造函数体内（以及参数初始化器中）未被实际访问的顶层参数，它们才会被安全移除；
getSuperParameters：收集在 super(...) 调用中被引用的参数——这些参数即使看起来"没用"也不能直接删除，因为它们承担了向父类传递依赖的职责；
parameterDeclaresProperty：判定参数是否声明了类属性（带 public/private/protected/readonly 修饰符），这类参数迁移后会变成类字段并伴随 this.xxx 访问模式的改写。

`nonNullableOptional`

这是最容易引发"迁移后出现新编译错误"的选项，其根源正是本文开头提到的类型精度差异。

当带有 @Optional 装饰器的参数注入失败时，Angular 运行时返回 null，因此 @Optional 参数的真实类型是 T | null。但由于装饰器无法影响 TypeScript 类型，大量存量代码把这类参数标成了不含 null 的错误类型。inject() 修正了这一类型（inject(TOKEN, {optional: true}) 推导为 T | null），于是迁移后可能冒出新的类型编译错误。

启用该选项后，迁移会在 inject() 调用后追加非空断言 !，使结果类型与旧的（不准确的）标注保持一致，代价是可能掩盖真实的空值问题。

ng generate @angular/core:inject --nonNullableOptional=true

转换前后对照：

// Before
import {Component, Inject, Optional} from '@angular/core';
import {TOKEN_ONE, TOKEN_TWO} from './token';

@Component()
export class MyComp {
  constructor(
    @Inject(TOKEN_ONE) @Optional() private tokenOne: number,
    @Inject(TOKEN_TWO) @Optional() private tokenTwo: string | null,
  ) {}
}

// After
import {Component, inject} from '@angular/core';
import {TOKEN_ONE, TOKEN_TWO} from './token';

@Component()
export class MyComp {
  // Note the `!` at the end.
  private tokenOne = inject(TOKEN_ONE, {optional: true})!;

  // Does not have `!` at the end, because the type was already nullable.
  private tokenTwo = inject(TOKEN_TWO, {optional: true});
}

重要规则：非空断言不会被添加到已经显式标为可空类型的参数上（如示例中的 tokenTwo: string | null），因为依赖这类参数的既有代码大概率已经对空值做了处理，强制加 ! 只会掩盖真实语义。对应的底层判定是 isNullableType 工具函数：它递归识别 undefined、void、null 字面量类型以及包含上述成员的联合类型（A | B）。

两个可选注入的取舍总结如下表：

旧代码标注类型	迁移产物	说明
`number`（非空）	`inject(TOKEN_ONE, {optional: true})!`	保留旧的"非空承诺"，靠 `!` 对齐旧类型
`string \| null`（可空）	`inject(TOKEN_TWO, {optional: true})`	类型本身已可空，不加 `!`

迁移的边界行为与注意事项

综合源码与官方文档，以下几点直接影响迁移结果，值得在实际运行前确认：

类内后续初始化代码的处理：迁移不只做"参数 → 字段"的机械改写。源码中存在两个内部选项 _internalCombineMemberInitializers 与 _internalReplaceParameterReferencesInInitializers，分别用于把构造体内的成员初始化语句尽量移回字段声明处、以及在初始化器中把对只读参数的引用改写为 this.param。例如形如 constructor(readonly service: Service) { this.foo = service.getFoo(); } 的模式可被整理为 readonly service = inject(Service); private foo = this.service.getFoo();。这解释了为何迁移后代码能保持较高的整洁度；
构造函数中非注入代码被保留：迁移只会移除与注入参数相关的部分；构造函数中真实存在的业务逻辑（如赋值之外的语句）不会被丢弃，未使用的参数移除由 getConstructorUnusedParameters 精确计算；
super 链的依赖传递：当构造参数被传入 super(...) 时，它们不会被简单删除，保证继承体系中父类仍能收到所需的依赖；
作用域与文件范围：迁移覆盖 build 与 test 两套 tsconfig 下的源码文件；若某文件因路径过滤或 canMigrateFile 判定不满足条件，会被整体跳过。

官方在 inject-migration 目录下的 README 中提供了与本文档一致的示例与选项说明，可作为命令参考的备份；而针对该迁移的自动化测试位于 inject_migration_spec.ts，覆盖了各类装饰器组合、继承场景与选项分支，如果你的代码碰巧命中了某个特殊形态（如抽象类、带 super 调用的继承、联合类型可选参数等），可以从测试用例中反查迁移的预期行为。

推荐的迁移流程

结合上述所有行为特征，一份稳妥的执行清单如下：

提交基线：迁移是批量改写类定义与导入的重构操作，务必先保证工作区干净可回滚（如先创建分支或确认 git 状态）；
小范围试点：先通过 --path=./src/app/xxx 限定到单个模块，运行：
```
ng generate @angular/core:inject --path=./src/app/xxx
```
随后执行构建与单元测试，确认无回归；
逐个决策选项：
- 若仓库存在带 Angular 装饰器的继承体系，优先开启 --backwardsCompatibleConstructors=true 观察是否有编译错误；
- 若迁移后出现与 @Optional 相关的新类型错误且你暂时不想重构空值处理逻辑，可开启 --nonNullableOptional=true，但应记录为技术债，后续逐步将类型收敛为真实的 T | null；
- 抽象类建议保持默认（不迁移），确需迁移时单独开启并手工复核每个继承该抽象类的具体实现；
全量执行并审查 diff：确认选项行为符合预期后，移除 --path 约束跑完整项目，逐文件审阅 diff，重点关注 ! 非空断言与保留的 super(...) 传递；
验证：运行完整构建、lint 与测试套件，尤其关注 inject() 调用点处于字段初始化器的类——字段初始化顺序与构造函数参数赋值的执行时机存在差异，任何在构造逻辑中访问尚未初始化字段的代码都需要人工确认。