Angular 路由懒加载迁移 route-lazy-loading：原理、用法与源码解析

2026-09-07 11:19:52作者：钟日瑜

路由懒加载（Lazy Loading）是 Angular 应用性能优化的关键手段，它让打包器把每个路由对应的组件代码拆成独立 chunk，避免把所有页面打进一个大体积的初始 JS 包。@angular/core:route-lazy-loading 这个官方 schematic（迁移脚本）正是用来把已 eagerly loaded（急切加载）的 standalone 组件路由自动改写为懒加载路由的自动化工具。本文基于 Angular 仓库中该迁移的官方文档与源码实现，完整说明它的使用方式、--path 参数、可识别的路由写法、内部工作流程、会被跳过的场景，以及迁移后的验证要点，让你既能安全地一键执行迁移，也能理解迁移器“能看到什么、改不了什么”。

迁移要解决的问题

在 Angular 应用中，路由可以指向一个组件，也可以指向一个按需加载的函数。两者的代码形态区别如下：

急切加载：component: HomeComponent——组件被打进路由所在模块/入口的 chunk，应用首屏会一并下载；
懒加载：loadComponent: () => import('./home.component').then(m => m.HomeComponent)——组件被拆成独立 chunk，只有真正导航到该路由时才下载。

当应用路由数量很多、每个页面都很重时，急切加载会让初始 JS bundle 越来越大，直接影响首屏加载速度。把“组件型路由”改造成“loadComponent 动态导入路由”，可以显著缩小首屏包体。而 route-lazy-loading 迁移能基于类型系统自动定位这类路由并完成改写，省去大量机械而容易出错的手工工作。

运行迁移命令

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

ng generate @angular/core:route-lazy-loading

该命令对应的源文件位于 packages/core/schematics/ng-generate/route-lazy-loading/index.ts。在仓库的 schematic 注册表 packages/core/schematics/collection.json 中即注册了名为 route-lazy-loading 的生成器，因此可通过上述 ng generate 直接触发。

执行结束后，迁移器会在终端输出如下统计信息（对应 index.ts 中的日志逻辑）：

Number of updated routes: ...——成功改写的路由数量；
Number of skipped routes: ...——被跳过的路由数量；
若存在跳过项，会逐条列出 path 与所在文件，并提示考虑先做 standalone 迁移后再重跑。

`path` 配置选项

默认情况下迁移会扫描整个应用。若希望只迁移部分文件（例如分阶段、分模块地推进改造），可传入 path 参数：

ng generate @angular/core:route-lazy-loading --path src/app/sub-component

path 的值是项目内的相对路径。从参数 schema 定义 packages/core/schematics/ng-generate/route-lazy-loading/schema.json 可以看到它的默认值是 ./（即整个项目），类型为字符串。

源码对 path 有明确的边界校验（见 index.ts）：

不允许以 .. 开头，即不能越出当前项目范围，否则抛出 Cannot run route lazy loading migration outside of the current project.；
传入的路径必须是一个目录（而非单个文件），否则抛出 Migration path ... has to be a directory.。

内部实现上，迁移器先通过 getProjectTsConfigPaths 收集项目所有 tsconfig 的构建路径（index.ts），找不到任何 tsconfig 时会直接报错终止；随后逐个 tsconfig 创建 TypeScript Program，仅处理文件名以目标路径开头的源文件。

迁移器能识别哪些路由写法

迁移并非靠字符串匹配，而是基于 TypeScript 类型检查器（TypeChecker） 识别真正的路由定义。源码中的判定函数集中在 util.ts，可识别的写法包括以下几类：

路由定义方式	判定函数	源码示例
`RouterModule.forRoot(...)`	`isRouterModuleCallExpression`	`RouterModule.forRoot(routes)`
`RouterModule.forChild(...)`	`isRouterModuleCallExpression`	`RouterModule.forChild([{...}])`
`Router.resetConfig(...)`	`isRouterCallExpression`	`this.router.resetConfig(routes)`
`provideRouter(...)`	`isProvideRouterCallExpression`	`provideRouter(routes)`
类型为 `Routes` 或 `Route[]` 的变量	`isAngularRoutesArray`	`const routes: Routes = [{...}]`

其中第 5 类要求变量类型确实是数组且其元素类型为来自 @angular/router 的 Route（util.ts 会核验类型声明所在文件包含 @angular/router 路径，避免误判同名类型）。路由数组的承载形态也覆盖了多种真实场景（见 to-lazy-routes.ts）：

内联数组：如 RouterModule.forRoot([{...}]) 直接写在调用括号里的情况；
变量引用：如 RouterModule.forRoot(routes)、provideRouter(routes)，会通过符号（Symbol）定位回 routes 变量的初始化表达式；
带类型标注的数组：const routes: Routes = [{...}]；
默认导出数组：包括 export default routes、export default [{...}]、export default [...] as Routes，以及 export { routes as default } 这类重导出写法。

迁移前后代码对比

对满足条件的路由，迁移效果就是把 component 属性替换为对应的 loadComponent 动态导入。

迁移前（eagerly loaded）：

// app.module.ts
import {Home} from './home';

@NgModule({
  imports: [
    RouterModule.forRoot([
      {
        path: 'home',
        // Home is standalone and eagerly loaded
        component: Home,
      },
    ]),
  ],
})
export class AppModule {}

迁移后（lazy loaded）：

// app.module.ts
@NgModule({
  imports: [
    RouterModule.forRoot([
      {
        path: 'home',
        // ↓ Home is now lazy loaded
        loadComponent: () => import('./home').then((m) => m.Home),
      },
    ]),
  ],
})
export class AppModule {}

注意迁移后的文件中，原先对 Home 的顶层静态 import 会被一并移除（to-lazy-routes.ts 统一收集待移除的导入并交给 ChangeTracker 删除），因为该组件现在仅通过动态 import() 引用。

除了上述文档示例，源码还支持两种细分情形：

默认导出组件：若组件声明带有 default 关键字，生成的懒加载代码为 loadComponent: () => import('./home')——不再追加 .then(m => m.Xxx)（见 to-lazy-routes.ts）；
别名导入组件：对于 import { Foo as Bar } 这类导入，迁移通过匹配导入的原始导出名（el.propertyName ?? el.name）来定位组件并据此引用（to-lazy-routes.ts）。

迁移器的工作流程与源码级原理

从源码结构看，整个迁移的处理链路分为四步（to-lazy-routes.ts）：

构建 TypeScript Program 与反射宿主：迁移使用 @angular/compiler-cli 的 TypeScriptReflectionHost 读取组件装饰器信息，并借助 ChangeTracker 统一记录所有文本改动；
发现路由数组：遍历源文件语法树，用上文 5 类判定函数找出所有路由数组的位置；
逐路由迁移：对数组中的每个对象字面量路由做如下检查（migrateRoute）：
- 先递归处理 children 子路由——嵌套路由同样会被迁移；
- 查找 component 属性；没有组件属性的路由（如 redirectTo、loadChildren 路由）直接跳过；
- 通过类型检查器解析组件类声明；
- 校验组件是否为 standalone；
- 校验组件不在路由数组所在文件内定义（同文件的组件无法用动态导入拆分，会被跳过）；
- 解析提供该组件的 import 语句及其模块路径；
- 生成 loadComponent 属性替换 component，并记录到 migratedRoutes；
应用改动：删除不再需要的组件 import，把文本插入/删除操作写回文件。

值得注意的是“standalone”的判定细节（util.ts）：组件必须带 @Component 装饰器；若装饰器对象里显式写了 standalone: true 则通过；若未写 standalone 属性，代码注释明确指出 standalone 在 v19 起默认为 true，因此同样视为可迁移对象。

从官方对迁移的自动化测试 packages/core/schematics/test/standalone_routes_spec.ts 可以看到，上述 73 处关于 loadComponent、provideRouter、resetConfig 的断言覆盖了 RouterModule.forRoot/forChild、provideRouter、带类型与不带类型的路由变量、内联路由、子路由递归、默认导出组件等多种输入形态，是理解该迁移行为边界的最佳参考资料。

哪些路由会被跳过：NgModule 声明的组件

迁移有一个硬性前提：只有 standalone 组件才能被转换为懒加载。如果路由指向的组件仍是在某个 @NgModule 的 declarations 中声明的传统组件，迁移器无法在路由层直接懒加载它，因而会将其列入 skippedRoutes。

迁移执行完会在终端输出所有被跳过路由的清单，包括：

该路由的 path；
定义路由的源文件位置。

例如输出会形如：

Note: this migration was unable to optimize the following routes, since they use components declared in NgModules:
- `home` path at `/path/to/app.routes.ts`
Consider making those components standalone and run this migration again.

针对这种场景，官方文档给出的建议流程是：

先使用现有的 standalone 迁移把 NgModule 中声明的组件转换成 standalone 组件——命令为 ng generate @angular/core:standalone，其说明文档位于 standalone 迁移指南，同样支持 --path 参数以限定迁移范围、按模块增量推进；
转换完成后再次运行 ng generate @angular/core:route-lazy-loading，让新成为 standalone 的路由组件也能被懒加载。

执行迁移前与迁移后的注意要点

结合官方文档结尾提示与迁移器 index.ts 的实现，建议遵循以下实践：

迁移范围可控：全应用规模较大时，先用 --path 限制到某个子目录（如一个 feature 模块目录）分步迁移，配合代码评审逐个合入，降低回归风险；
迁移前提交：确保工作区干净（已 commit），便于迁移结果有误时随时回退；
迁移后必须人工验证：官方在命令完成时会输出 IMPORTANT! Please verify manually that your application builds and behaves as expected.——这是自动重构的通行准则。改动的是导入与路由加载方式，运行期行为（懒加载失败、路径错误、循环依赖）需要靠 ng build 与真实页面导航验证；
理解被跳过清单：终端列出的 skipped 路由并非失败，而是提示你哪些组件还在 NgModule 内，可作为后续 standalone 化改造的待办清单；
对代码分块的影响：懒加载是否真正生效取决于构建工具（webpack/esbuild）按动态导入拆分包，迁移只负责产出正确的 loadComponent 语法，最终包体收益请通过构建产物分析确认。