# @edx/frontend-platform 中文文档

规范地址：https://npmcn.com/package/%40edx/frontend-platform/

版本：8\.7\.1
npm 元数据更新时间：2026-07-10T14:29:54.048Z
中文译文更新时间：2026-11-13T07:49:26.948Z
软件包许可：AGPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40edx/frontend-platform
原文对照：https://npmcn.com/package/%40edx/frontend-platform/?lang=original
项目主页：https://github.com/openedx/frontend-platform#readme
源码仓库：https://github.com/openedx/frontend-platform

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，178 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：19 个
- peer 依赖：react ^16\.9\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0，redux ^4\.0\.4，react-dom ^16\.9\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0，prop-types \>=15\.7\.2 \<16\.0\.0，react-redux ^7\.1\.1 \|\| ^8\.1\.1，@openedx/paragon \>= 21\.5\.7 \< 24\.0\.0，react-router-dom ^6\.0\.0，@openedx/frontend-build \>= 14\.0\.0
- 首次发布：2019-11-21T22:37:43.619Z
- 最新版本发布：2026-07-01T16:13:06.278Z
- 近 30 天下载量：37846（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：192（近 12 个月 7 个）

## 中文简介

Open edX微前端应用程序的基础应用框架.

## 安装

```sh
npm install @edx/frontend-platform
```

也可以使用：`pnpm add @edx/frontend-platform`、`yarn add @edx/frontend-platform`、`bun add @edx/frontend-platform`

## README

[![Build Status](https://github.com/openedx/frontend-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/openedx/frontend-platform/actions/workflows/ci.yml) [![Codecov](https://img.shields.io/codecov/c/github/edx/frontend-platform)](https://codecov.io/gh/edx/frontend-platform) [![NPM Version](https://img.shields.io/npm/v/@edx/frontend-platform.svg)](https://www.npmjs.com/package/@edx/frontend-platform) [![npm\_downloads](https://img.shields.io/npm/dt/@edx/frontend-platform.svg)](https://www.npmjs.com/package/@edx/frontend-platform) [![license](https://img.shields.io/npm/l/@edx/frontend-platform.svg)](https://github.com/openedx/frontend-platform/blob/master/LICENSE) [![semantic release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

# 概览

见 [完整文档的 GitHub 页面网站](https://openedx.github.io/frontend-platform/)。 。 。 .

前端-平面是Open edX微前端应用程序及其辅助库的适度应用框架. 它提供几种基础服务,所有Open edX微前端都应该有:

| 服务 | 模块位置 |
| --- | --- |
| 分析 | @edx/前端-平台/分析 |
| 日志 | @ edx/ 前端- 平台/ logb |
| 认证的 API 客户端( 自动) | @ edx/ 前端- 平台/ 自动 |
| 国际化(i18n) | @edx/前端-平台/i18n |
| 杂项(init、config、pubSub、utils) | @ edx/ 前端- 平台 |

* * *

此外,前端平台还提供可扩展的应用程序初始化生命周期来帮助管理上述服务的配置,使应用程序开发人员能够专注于地物开发.

## 开始

### 未升级节点/ npm 的一次性设置

#### 安装 nvm

这被强烈地推荐为能够利用不同的节点/npm版本. 一段时间以来,不同的寄存器可能使用不同的节点/npm版本.

#### 切换到此 repo 的节点/ npm 版本

在项目的根目录中, 运行 `nvm use` 将环境设置为正确的节点版本。 如果没有安装所需的节点或npm版本,nvm将提示您安装.

#### 清理出旧节点模块并重新安装

需要这个步骤是因为节点现在使用不同的包锁格式,必须重新安装 基于此新软件包文件的依赖性 。 删除 `node_modules`运行 `npm ci`。 。 。 .

### 标准开始步骤

1.  `npm install`
2.  `npm start`
3.  打开 http://local.openedx.io:8080 查看示例应用.

## 建筑

上述四个基础服务(分析、认证、i18n和伐木)是通过前端平台的API层,作为对应用程序的进口。 初始化序列创建了每个服务的一例并暴露出其作为功能输出的方法,在服务实施与应用代码中的使用之间形成了一层抽象.

每类服务都有一份记录的API合同,服务执行必须履行。 这样可以在必要时使用不同的服务实施,而无需更新以消耗应用程序.

### 服务架构

内部,服务实施与其余平台严格隔离. 他们的阶级以他们的依附关系作为其建构者的论据. 这意味着,例如,如果分析依赖于伐木,则需要参考符合以下条件的实例: `LoggingService` 界面作为当它被即时化时的选项。 它不能直接从日志模块导入 。 换句话说,默认的服务实施可能为了方便而与服务接口合用同一位置,但他们理论上可以住在自己的寄存器中,这不需要任何重构.

同样地,平台代码也不应该使用由于同样原因不属于有文件记载的界面的服务方法.

### 应用程序初始化

前端平台提供了一个 `initialize()` 函数,用于设置和配置应用程序。 这个 `initialize()` 函数使用一组 [合理默认](https://en.wikipedia.org/wiki/Convention_over_configuration) 除非另有说明,否则用反映Open edX在分析、认证、国际化和伐木方面最佳做法的服务来拖住应用程序.

初始化过程分出一系列阶段进行,为初始化的应用代码提供了连接到进程并按所希望的自定义设置的机会:

-   初始化前
-   Pub/Sub 已初始化
-   已装入环境配置文档
-   日志服务已初始化
-   认证服务已初始化
-   分析服务初始化
-   国际化服务初始化
-   应用程序已就绪

大多数的应用不需要做任何特殊的事情.

### 应用程序配置

当应用程序加载时,会从中加载已知环境变量列表 `process.env` 进入它通过它暴露的物体 `getConfig` - 这里的要点主要是 把我们的代码 与使用 `process.env` 这也许并不总是我们选择配置应用程序的方式。 应用程序初始化生命周期支持运行时间配置,同时通过 `config` 处理器,记录在 [初始化函数](https://edx.github.io/frontend-platform/module-Initialization.html#~initialize)。如果想要将一个变量输入它不期望的配置,您可以使用 [`mergeConfig`](https://edx.github.io/frontend-platform/module-Config.html#~mergeConfig) 初始化时从 `process.env`。 。 。 .

这样的例子可能是这样的:

```
initialize({
  // ... other initialization options
  handlers: {
    config: () => {
      mergeConfig({
        CUSTOM_VARIABLE: process.env.CUSTOM_VARIABLE || null,
      }, 'Custom app config');
    },
  },
});
```

当通过运行时配置 `mergeConfig` 如上所述, `getConfig` 要返回配置对象中添加的密钥和值,必须在组件的渲染寿命周期内调用。 若为 `getConfig` 被调用到组件渲染寿命周期之外,自定义配置密钥/值对最初将不会是返回对象的一部分 `getConfig`。例如:

```jsx
import { getConfig } from '@edx/frontend-platform/config';

// The runtime configuration `CUSTOM_VARIABLE` added in the above code snippet will not appear here. This is
// because `getConfig` is called before `mergeConfig` is executed to add the custom runtime configuration.
console.log(getConfig().CUSTOM_VARIABLE); // returns undefined

const ExampleComponent = () => {
  // This returns the value as expected since it is called after `mergeConfig` has already been executed.
  console.log(getConfig().CUSTOM_VARIABLE)
};
```

#### 覆盖默认外部链接

A 类 `getExternalLinkUrl` 函数在 `config.js` 用于覆盖默认的外部链接。 要使用此功能,请提供一个将默认链接映射到自定义链接的对象. 此对象应添加到 `config` 定义对象 `env.config.[js,jsx,ts,tsx]`名称 `externalLinkUrlOverrides`。这里有一个例子:

```js
// env.config.js

const config = {
  // other custom configuration here
  externalLinkUrlOverrides: {
    "https://docs.openedx.org/en/latest/educators/index.html": "https://custom.example.com/educators/index.html",
    "https://creativecommons.org/licenses": "https://www.tldrlegal.com/license/creative-commons-attribution-cc",
  },
};

export default config;
```

### 服务接口

前端平台提供的每项服务(分析、认证、i18n、伐木)都有一个API合同,该合同的所有实施都得到保证。 使用前端平台的应用程序可以通过一套方便的导出功能使用其配置的服务. 一个想要使用服务接口的应用程序只需要通过初始化()函数来初始化它们,可以选择地提供所希望的自定义服务接口(你可能不需要).

![Service interface](https://npmcn.com/package/%40edx/frontend-platform/service-interface.png)

### 服务实施

此寄存器包含默认服务执行以方便. 这些实施与消费服务接口合用同一地点,以方便开发,但两者应保持不变 _严格_ 模块化和分离.

包括的服务实施包括:

-   新遗迹 (博客)
-   部分(分析)
-   Axios/JWT(秋季)
-   反应入(i18n)

注:截至本文,i18n为 _没有_ 相会相会. 这个 `initialize()` 函数不允许应用程序提供替代的 i18n 执行;这是因为 i18n 的接口和执行尚未分离和模块化.

# 本地开发和测试

在修改前端平台时, 请确保手动运行位于其中的包含实例应用程序 `./example`。示例应用包括两个路径,用于测试未经认证和认证的用户。 要启动示例应用程序, 请运行 `npm start` 从根目录.

如果您要测试本地微前端对前端平台的修改, 请遵循这里的方向 : [https://github.com/openedx/frontend-building# 本地-模块-配置-为网络包装](https://github.com/openedx/frontend-build#local-module-configuration-for-webpack)

## 获得示例应用程序与导师 Dev 环境合作

部分的示例应用功能包括API请求在用户的配置信息中得到登录. 由于CORS的限制,此请求默认会失败. 为了克服这个,补丁 `openedx-lms-development-settings` 以下设置( 通过一个导师插件) :

```python
# Used for the example app in the frontend-plugin library
CORS_ORIGIN_WHITELIST.append("http://local.openedx.io:8080")
LOGIN_REDIRECT_WHITELIST.append("local.openedx.io:8080")
CSRF_TRUSTED_ORIGINS.append("http://local.openedx.io:8080")
```

确保插件安装、启用并运行 `tutor dev restart lms` 以确保新配置被取出.

# 生产部署战略

对于前端站台上所搭建的任何MFE,部署策略将大致如下:

1.  在命令行上运行带有环境变量的构建脚本,以便在任何相关的配置中通过. 示例
    
    ```bash
    NODE_ENV=development BASE_URL=open.edx.org ETC=etc npm run build
    ```
    
    这将创建一个包含可部署文物的Dist/目录.
    
2.  复制 dist/ 的内容到网络服务器 .
    
3.  配置用于指向您的 MFE 的平台 。 (详情关于这个即将到来)

## 常见问题

### @edx/frontend-platform 是什么？

Open edX微前端应用程序的基础应用框架\.

### 如何安装 @edx/frontend-platform？

在项目目录运行 npm install @edx/frontend-platform，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.9\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0）、redux（^4\.0\.4）、react-dom（^16\.9\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0）、prop-types（\>=15\.7\.2 \<16\.0\.0）、react-redux（^7\.1\.1 \|\| ^8\.1\.1）、@openedx/paragon（\>= 21\.5\.7 \< 24\.0\.0）、react-router-dom（^6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 intl-imports\.js、transifex-utils\.js，可以用 npx intl-imports\.js 直接运行。

### @edx/frontend-platform 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @edx/frontend-platform 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @edx/frontend-platform 可以商用吗？

@edx/frontend-platform 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @edx/frontend-platform 的下载量有多少？

根据 npm 官方下载统计，@edx/frontend-platform 在 2026/10/13 – 2026/11/11 这 30 天内被下载 37,846 次，日均约 1,262 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @edx/frontend-platform 还在维护吗？

最新版本 8\.7\.1 发布于 2026/07/02（4 个月前）；至今共发布 192 个版本，其中过去 12 个月发布了 7 个；首次发布于 2019/11/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。