抠丁客 抠丁客
项目
编辑 (2025/12/24)

环境配置

每个应用程序都需要一些环境变量。在 Angular 生态中，通常通过 environment.ts、environment.prod.ts 等文件进行管理。ABP 框架同样采用这种方式。

当前的 Environment 配置包含以下子配置类：

export interface Environment {
  apis: Apis;           // API 配置
  application: Application;  // 应用配置
  oAuthConfig: AuthConfig;   // 认证配置
  production: boolean;       // 生产环境标识
  remoteEnv?: RemoteEnv;     // 远程环境配置（可选）
}

API 配置

export interface Apis {
  [key: string]: ApiConfig;  // 支持多个 API 配置
  default: ApiConfig;        // 默认 API 配置
}

export interface ApiConfig {
  [key: string]: string;
  rootNamespace?: string;    // 根命名空间
  url: string;              // API 地址
}

API 配置必须包含默认配置，同时可为不同模块添加额外配置。例如，您可能希望不同模块连接不同的 API。

参考以下示例：

{
  // ...
  "apis": {
    "default": {
      "url": "https://localhost:8080"
    },
    "AbpIdentity": {
      "url": "https://localhost:9090"
    }
  }
  // ...
}

当调用 AbpIdentity 模块的 API 时，请求将发送至 "https://localhost:9090"，其他请求则发送至 "https://localhost:8080"。

  • rootNamespace (新增) : 相关 API 的根命名空间，例如 Acme.BookStore

应用配置

export interface Application {
  name: string;      // 应用名称
  baseUrl?: string;  // 基础地址
  logoUrl?: string;  // 徽标地址
}
  • name: 后端应用名称。如果未提供 logoUrl，该名称也会被 logo.component 使用。
  • logoUrl: 应用徽标地址，由 logo.component 使用。
  • baseUrl: 详细信息请参考

认证配置

我们使用 angular-oauth2-oidc 进行认证。请查阅其官方文档。

远程环境配置

某些应用需要将现有配置集成到全局使用的 environment 中。ABP 框架对此提供了开箱即用的支持。

要将现有 JSON 配置集成到 environment 中，您需要设置 remoteEnv：

export type customMergeFn = (
  localEnv: Partial<Config.Environment>,
  remoteEnv: any
) => Config.Environment;

export interface RemoteEnv {
  url: string;          // 配置获取地址
  mergeStrategy: "deepmerge" | "overwrite" | customMergeFn;  // 合并策略
  method?: string;      // HTTP 方法
  headers?: ABP.Dictionary<string>;  // 请求头
}
  • url *: 必填。用于获取环境配置的 URL 地址。
  • mergeStrategy *: 必填。定义本地与远程 environment JSON 的合并方式：
    • deepmerge: 递归合并本地和远程配置。如果两者存在相同嵌套路径，远程配置优先级更高。
    • overwrite: 直接使用远程配置，忽略本地配置。
    • customMergeFn: 可自定义合并函数（如示例所示）。该函数接收 localEnv: Partial<Config.Environment> 和 remoteEnv 两个参数，需返回 Config.Environment 对象。
  • method: 获取环境配置时使用的 HTTP 方法。默认值：GET。
  • headers: 如需为请求添加额外头部，可通过此字段设置。

通过环境配置核心提供程序

environment 变量来自 Angular 主应用：

import { environment } from '../environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideAbpCore(
      withOptions({
        environment,
        ...
      })
    ),
    ...
  ],
};

EnvironmentService

EnvironmentService 是一个单例服务（已在应用根级别提供），用于在内部存储中维护环境配置。

使用前准备

要使用 EnvironmentService，必须将其作为依赖项注入到类中：

import { EnvironmentService } from '@abp/ng.core';
import { inject } from '@angular/core';

@Component({
  /* 类元数据 */
})
class DemoComponent {
  private environment = inject(EnvironmentService);
}

由于该服务已在根级别提供，无需在模块或组件/指令级别重复提供。

获取方法

EnvironmentService 提供多种获取方法，可用于获取特定值或完整环境对象。

方法名以"$"结尾的方法（如 getEnvironment$）返回 RxJs 流。当状态被设置或修改时，这些流会触发更新。

获取环境对象

使用 EnvironmentService 的 getEnvironment 或 getEnvironment$ 方法获取完整环境对象：

// this.environment 是 EnvironmentService 实例

const environment = this.environment.getEnvironment();

// 或使用响应式方式
this.environment.getEnvironment$().subscribe((environment) => {
  // 在此使用环境配置
});

获取 API 地址

getApiUrl 或 getApiUrl$ 方法用于从环境对象中获取特定 API 地址：

// this.environment 是 EnvironmentService 实例

const apiUrl = this.environment.getApiUrl();
// 返回 environment.apis.default.url

this.environment.getApiUrl$("search").subscribe((searchUrl) => {
  // 返回 environment.apis.search.url
});

该方法根据传入的键名返回对应 API 的 url 属性。如果未提供键名，则默认使用 'default'。

设置环境配置

EnvironmentService 提供 setState 方法用于更新状态值：

// this.environment 是 EnvironmentService 实例

this.environment.setState(newEnvironmentObject);

请注意在应用初始化时无需手动调用此方法，因为环境变量在启动时已自动存储。

环境属性

完整属性列表请参考 Environment 类型定义，可在 environment.ts 文件 中查看。

在本文档中