企业官网建设流程全解析

• 前端
• 状态管理

导读

@ngrx/router-store是 NgRx 生态中连接 Angular Router 与 Store 的核心绑定库，它通过监听路由事件并把路由状态同步进 Redux 式的 Store，让路由导航可以被 reducer、effect 统一管理。本文围绕 projects/www/src/app/pages/guide/router-store/install.md 讲解两种安装方式：推荐的一行命令ng add（会自动完成依赖安装与代码注入），以及完全手动安装的流程，并结合仓库源码揭示每一步背后的实际改动，帮助你理解安装之后项目里到底发生了什么。

方式一：使用ng add自动安装（推荐）

ng add是 Angular CLI 提供的一键集成机制。在项目根目录执行以下命令即可安装最新版的 Router Store：

ng add @ngrx/router-store@latest

命令背后的逻辑定义在仓库的 ng-add 示意图（modules/router-store/schematics/ng-add/index.ts）中，并由 collection.json 注册为ng-add（别名init）示意图。示意图会依次完成三件事：

1. 更新package.json>dependencies：把@ngrx/router-store加入项目依赖。从源码看，这一步由addNgRxRouterStoreToPackageJson()函数实现，写入的版本号取自当前的platformVersion（即与 @ngrx/router-store 包自身版本一致，当前仓库版本为 22.0.1，见 package.json）。
2. 运行npm install：示意图通过NodePackageInstallTask触发实际的依赖安装，无需你手动执行。
3. 默认向app.config.ts的ApplicationConfig注入provideRouterStore()：在 standalone 应用下，示意图定位项目入口文件的 bootstrap 配置，把provideRouterStore()添加进 providers 数组。snapshot 测试 index.spec.ts.snap 展示了注入后的预期结果：

import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core'; import { provideRouterStore } from '@ngrx/router-store'; export const appConfig: ApplicationConfig = { providers: [ provideBrowserGlobalErrorListeners(), provideRouterStore() ] };

如果你指定了--module/--path等 flags，示意图会按 flags 定位到对应的 NgModule 或配置文件并完成更新。

可选ng addflags

这三个 flag 与 schema 定义一一对应：schema.json 中path使用$source: "workingDirectory"获取默认值，project有别名p，module有别名m且默认值为"app"；此外 schema 还暴露了一个文档未展开的隐藏 flag--skipPackageJson（布尔值，默认false），用于跳过对package.json的自动修改。

示意图的底层处理逻辑：NgModule 与 Standalone 两条分支

从 ng-add 示意图 可以看到，示意图启动时会先判断应用是否为 standalone（通过isStandaloneApp检查入口文件），然后选择两条注入路径：

• Standalone 应用：走addStandaloneConfig(options)，如果provideRouterStore已在入口配置中调用则直接跳过（避免重复注入），否则调用addFunctionalProvidersToStandaloneBootstrap将其写入 bootstrap providers。
• NgModule 应用：走addImportToNgModule(options)，它通过 TypeScript AST 解析目标模块文件，插入import { StoreRouterConnectingModule } from '@ngrx/router-store'并把StoreRouterConnectingModule.forRoot()追加到模块的imports数组（见 index.ts）。

该逻辑有完整的单元测试覆盖，见 ng-add/index.spec.ts：测试验证了package.json会被更新、skipPackageJson: true时跳过更新、默认注入StoreRouterConnectingModule.forRoot()、指定module时可精确注入、目标模块不存在时报错，以及 standalone 应用的 snapshot 注入结果。

provideRouterStore()与StoreRouterConnectingModule的关系

无论哪种注入方式，最终落地的都是同一套 providers。StoreRouterConnectingModule.forRoot()内部只是封装了provideRouterStore(config)并把它作为 module providers 返回（见 router_store_module.ts），二者等价，因此：

// NgModule 方式 imports: [StoreRouterConnectingModule.forRoot()] // Standalone 方式 providers: [provideRouterStore()]

provideRouterStore()的实现位于 provide_router_store.ts，它根据配置自动选择合适的序列化器：默认使用MinimalRouterStateSerializer（routerState为Full时改用FullRouterStateSerializer），并注册StoreRouterConnectingService在应用初始化阶段连接 Router 与 Store。一个完整的 standalone 注册示例：

bootstrapApplication(AppComponent, { providers: [ provideStore({ router: routerReducer }), provideRouterStore(), ], });

方式二：手动安装

如果你的项目不便使用ng add（例如 CI 环境、自定义构建流程或希望完全掌控每个文件），也可以手动完成安装。

首先使用包管理器安装依赖，安装命令取决于项目所用工具：

# 使用 npm npm install @ngrx/router-store # 使用 Yarn yarn add @ngrx/router-store # 使用 pnpm（当前仓库使用 pnpm workspace，参见 pnpm-workspace.yaml） pnpm add @ngrx/router-store

注意：@ngrx/router-store依赖@ngrx/store与 Angular Router 相关包。当前仓库 package.json 声明了 peerDependencies：@angular/common、@angular/core、@angular/router（均为^22.0.0）、@ngrx/store（22.0.1）以及rxjs ^6.5.3 || ^7.5.0，请确保你的项目满足这些版本要求。

装完依赖后，需要把路由状态接入 Store：

// NgModule 方式 import { StoreModule } from '@ngrx/store'; import { RouterModule } from '@angular/router'; import { StoreRouterConnectingModule } from '@ngrx/router-store'; @NgModule({ imports: [ StoreModule.forRoot({}), RouterModule.forRoot([ { path: '', component: SimpleCmp }, { path: 'next', component: SimpleCmp }, ]), StoreRouterConnectingModule.forRoot(), ], }) export class AppModule {}

// Standalone 方式 import { provideStore } from '@ngrx/store'; import { provideRouterStore } from '@ngrx/router-store'; export const appConfig: ApplicationConfig = { providers: [ provideStore(), provideRouterStore(), ], };

安装后验证

安装完成后可以检查以下位置确认集成成功：

• package.json：dependencies中出现"@ngrx/router-store": "22.0.1"（版本以实际安装为准）。
• 配置入口：standalone 应用检查app.config.ts中是否出现provideRouterStore()；NgModule 应用检查根模块imports中是否有StoreRouterConnectingModule.forRoot()。
• 类型层面：若项目启用了strict模式，编译不报错即说明序列化器与 provider 类型已正确接入。

可结合仓库中的示例应用参考完整集成形态，例如 modules/router-store/src/provide_router_store.ts 中provideRouterStore的@usageNotes示例，以及 standalone-app 中的实际注册方式。

小结

对于绝大多数场景，推荐使用ng add @ngrx/router-store@latest完成安装，再由示意图自动生成的provideRouterStore()将 Angular Router 与 Store 无缝连接起来。如果你需要更细粒度的路由序列化与状态同步配置，可在此基础上继续阅读 router-store 相关的 configuration 与 serializer 文档。

• 前端
• 状态管理