# @eggjs/core 中文文档

规范地址：https://npmcn.com/package/%40eggjs/core/

版本：7\.1\.0
npm 元数据更新时间：2026-10-07T08:18:24.752Z
中文译文更新时间：2026-11-13T09:22:46.722Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eggjs/core
原文对照：https://npmcn.com/package/%40eggjs/core/?lang=original
项目主页：https://github.com/eggjs/egg/tree/next/packages/core
源码仓库：https://github.com/eggjs/egg

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

- 包体积（解压后）：166 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：16 个
- 首次发布：2024-06-17T02:36:23.846Z
- 最新版本发布：2026-10-07T08:18:24.418Z
- 近 30 天下载量：6312（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 33 个）

## 中文简介

基于 @eggjs/koa 的核心插件框架

## 安装

```sh
npm install @eggjs/core
```

也可以使用：`pnpm add @eggjs/core`、`yarn add @eggjs/core`、`bun add @eggjs/core`

## README

# @eggjs/ 分数

[![NPM version](https://img.shields.io/npm/v/@eggjs/core.svg?style=flat-square)](https://npmjs.org/package/@eggjs/core) [![Known Vulnerabilities](https://snyk.io/test/npm/@eggjs/core/badge.svg?style=flat-square)](https://snyk.io/test/npm/@eggjs/core) [![npm download](https://img.shields.io/npm/dm/@eggjs/core.svg?style=flat-square)](https://npmjs.org/package/@eggjs/core) [![Node.js Version](https://img.shields.io/node/v/@eggjs/core.svg?style=flat)](https://nodejs.org/en/download/)

基于核心插件框架 [@eggjs/koa (英语)](https://github.com/eggjs/koa)。 。 。 . 共同用途和无害环境管理 [hy](https://github.com/isaacs/tshy)。 。 。 .

**别直接用,你看 [鸡蛋](https://github.com/eggjs/egg)。 。 。 .**

## 使用量

目录结构

```bash
├── package.json
├── app.ts (optional)
├── agent.ts (optional)
├── app
|   ├── router.ts
│   ├── controller
│   │   └── home.ts
|   ├── extend (optional)
│   |   ├── helper.ts (optional)
│   |   ├── filter.ts (optional)
│   |   ├── request.ts (optional)
│   |   ├── response.ts (optional)
│   |   ├── context.ts (optional)
│   |   ├── application.ts (optional)
│   |   └── agent.ts (optional)
│   ├── service (optional)
│   ├── middleware (optional)
│   │   └── response_time.ts
│   └── view (optional)
|       ├── layout.html
│       └── home.html
├── config
|   ├── config.default.ts
│   ├── config.prod.ts
|   ├── config.test.ts (optional)
|   ├── config.local.ts (optional)
|   ├── config.unittest.ts (optional)
│   └── plugin.ts
```

然后从下面的代码开始

```ts
import { EggCore as Application } from '@eggjs/core';

const app = new Application({
  baseDir: '/path/to/app',
});
app.ready(() => {
  app.listen(3000);
});
```

## 鸡蛋记录器

EggLoader 可以轻松地在您的文件中加载文件或目录 [鸡蛋](https://github.com/eggjs/egg) 项目. 此外,还可以自定义低等API的加载器.

### 构造器

-   {String} BaseDir - 当前应用程序目录
-   {Object} app - 彩蛋应用实例
-   {Object} 插件 - 合并插件进行测试
-   {logger} 日志 - 日志实例, 默认为控制台

### 高级APIs

#### 自动加载

装入配置/ 插件. ts

#### aync 负载配置

装入配置/ 配置. ts 和配置/ { serverEnv}. ts

若为 `process.env.EGG_APP_CONFIG` 已存在,然后将解析并覆盖配置.

#### 自动加载控制器

装入应用程序/控制器

#### async 负载中间软件

装入应用程序/中件

#### 代理负载应用

装入应用程序/扩展/应用程序.ts

#### async load 文本扩展

装入app/extend/context.ts

#### 请求删除

装入应用/扩展/请求.ts

#### async 负载响应扩展

装入应用/扩展/响应.ts

#### async 加载帮助扩展

装入app/extend/ helper.ts

#### async 负载 CustomApp

装入app.ts,如果app.ts导出启动类,则触发配置DidLoad

#### 自动加载

装入代理.ts,如果代理.ts导出启动类,则触发配置DidLoad

#### 代理负载服务

装入应用/服务

### 低级 API

#### 获取ServerEnv ()

通过 `serverEnv`。 。 。 . 您可以通过电话直接访问 `this.serverEnv` 即时反应后.

| 服务器 Env | 说明 |
| --- | --- |
| 默认 | 默认环境 |
| 测试 | 系统集成测试环境 |
| 音标 | 生产环境 |
| 当地 | 本地环境在您的计算机上 |
| 单位测试 | 单元测试环境 |

#### 获取数据( )

获取框架目录 。 新的框架通过延伸蛋, 然后可以使用此函数来获取所有框架.

#### 获取损失单位( C)

负载Unit是一个可以被 EggLoader 装入的目录,因为它具有相同的结构.

此函数将获得添加负载 Units 遵循顺序 :

1.  插件
2.  框架
3.  应用

加载单元有一个路径和一个类型。 类型必须是其中之一: _应用_, (中文(简体) ), _框架_, (中文(简体) ), _插件_。 。 。 .

```js
{
  path: 'path/to/application',
  type: 'app'
}
```

#### 获取 Appname ()

获取应用程序名称 _软件包.json_

#### 应用程序信息

获取应用程序的信息

-   pkg: (英语) `package.json`
-   名称: 来自 `package.json`
-   baseDir: 当前应用程序目录
-   env: 等于服务器 Env
-   Home: OS的主目录
-   root: 本地和单位测试时的基准定义, 其他环境时的基准定义

#### async 加载文件( 文件路径)

要装入一个文件 . **说明:** 文件必须导出为函数 .

#### aync loadToApp(目录、属性、加载器选项)

从应用程序中的目录中装入文件 .

调用 `this.loadToApp('$baseDir/app/controller', 'controller')`,然后你可以使用它通过 `app.controller`。 。 。 .

#### aync 负载ToContext(目录、属性、加载器选项)

要从目录中装入文件, 它会被绑定上下文 .

```ts
// define service in app/service/query.ts
export default class Query {
  constructor(ctx: Context) {
    super(ctx);
    // get the ctx
  }

  async get() {}
}

// use the service in app/controller/home.ts
export default async (ctx: Context) => {
  ctx.body = await ctx.service.query.get();
};
```

#### async 加载Extend( 名称, 目标)

装入器app/extend/xx.ts到目标,例如,

```ts
await this.loadExtend('application', app);
```

### 装入器选项

\* 帕拉姆 \* 类型 \* 说明 \* \* \* |--------------------------------------------------------------- ---------------------------------------- --- --------- ------- --------- -- -- - -- - -- -- - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - -- - - - - - - - - - - - - - - - qq 目录 qq `String/Array` 要装入的目录 {} 目标 `Object` qq 从已装入的文件附加目标对象qq {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}对吗 `String/Array` 装入时匹配文件, 默认为 `**/*.js`(如果进程.env.EGG\*TYPESCRIPT是真实的,默认为 `[ '\*\*/\_.(js | ts)', '!\*_/_.d.ts' ]`) (中文(简体) ) {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}不理会 `String/Array` qq 装入时忽略文件qq 开始器 `Function` xq自定义文件导出, 接收两个参数, 第一个是注入对象( 如果不是 js 文件, 将是内容缓冲), 第二个是 an `options` 包含对象 `path` | 案件史蒂尔 `String/Function` qq 在将文件路径转换为属性列表时设置属性大小写 。 | qq 覆盖qq `Boolean` 确定是否在获得同名时覆盖属性 打电话 `Boolean` 确定当出口为函数时是否引用 {} 注射量为: `Object` qq 函数引用时作为参数的对象qq 过滤器 `Function` qq 函数过滤可以装入的导出qq

## 时间安排

EggCore 记录启动进度 `Timing`,包括:

-   进程启动时间
-   脚本启动时间( 节点不会像 `process.uptime` 要记录脚本开始运行时间,框架可以执行带有节点的启动前文件 `--require` 要设置的选项 `process.scriptTime`(中文(简体) )
-   `application start` 或者说 `agent start` 时间
-   装入时间
-   `require` 会期

### 开始

开始记录一个项目 。 如果项目退出,则结束旧项目并开始新的项目.

-   {String} 名称 - 记录项名
-   {number} \[start\] - 记录项开始时间,默认为 Date.now()

### 结束

结束一个东西.

-   {String} 名称 - 尾项名

### 给杰森

生成所有记录项到 json

-   {String} 名称 - 记录项名
-   {数量} 开始 - 项目开始时间
-   {数量} 结束 - 项目结束时间
-   {数目} 持续时间 - 项目持续时间
-   {数目} pid - pid
-   {编号}索引-项目索引

## 问题和建议

请打开一个问题 [这里](https://github.com/eggjs/egg/issues)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40eggjs/core/LICENSE)

## 贡献者

[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)

制造的 [贡献者-img](https://contrib.rocks/)。 。 。 .

## 常见问题

### @eggjs/core 是什么？

基于 @eggjs/koa 的核心插件框架

### 如何安装 @eggjs/core？

在项目目录运行 npm install @eggjs/core，或使用 pnpm add / yarn add / bun add。

### @eggjs/core 支持 TypeScript 吗？

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

### @eggjs/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eggjs/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eggjs/core 可以商用吗？

@eggjs/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eggjs/core 的下载量有多少？

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

### @eggjs/core 还在维护吗？

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