Egg.js 快速入门指南：从零开始构建企业级 Node.js 应用

阮然阳Ian

于 2025-06-02 09:01:18 发布

阅读量446

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/gitblog_01057/article/details/148374738

Egg.js 快速入门指南：从零开始构建企业级 Node.js 应用

前言

Egg.js 是一款基于 Koa 的企业级 Node.js 框架，由阿里团队开源并维护。它奉行"约定优于配置"的设计理念，提供了一套完整的开发规范和插件体系，特别适合构建复杂的企业级应用。本文将带你从零开始，快速掌握 Egg.js 的核心开发流程。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

操作系统：macOS/Linux/Windows 均可
Node.js 环境：建议使用最新的 LTS 版本（如 14.x/16.x），最低要求 8.x 版本
npm 版本：不低于 6.1.0

两种项目创建方式

Egg.js 提供了两种项目初始化方式，适合不同场景：

1. 脚手架快速创建（推荐新手）

这是最简单的入门方式，只需执行以下命令：

mkdir my-egg-project && cd my-egg-project
npm init egg --type=simple
npm install

启动开发服务器：

npm run dev

访问 http://localhost:7001 即可看到欢迎页面。

2. 手动搭建（适合学习原理）

为了深入理解 Egg.js 的工作原理，我们也可以手动搭建项目：

mkdir egg-manual && cd egg-manual
npm init -y
npm install egg --save
npm install egg-bin --save-dev

在 package.json 中添加启动脚本：

{
  "scripts": {
    "dev": "egg-bin dev"
  }
}

核心概念实战

1. 控制器(Controller)与路由

控制器负责处理请求并返回响应。创建第一个控制器：

// app/controller/home.js
const Controller = require('egg').Controller;

class HomeController extends Controller {
  async index() {
    this.ctx.body = 'Hello Egg.js';
  }
}

module.exports = HomeController;

配置路由映射：

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};

2. 配置文件

Egg.js 采用多环境配置机制，默认配置文件：

// config/config.default.js
exports.keys = 'your-secret-key'; // 用于加密的密钥

3. 静态资源处理

Egg.js 内置了静态资源插件，只需将资源放入 app/public 目录：

app/public
├── css
│   └── style.css
└── js
    └── app.js

4. 模板渲染

安装 Nunjucks 模板引擎：

npm install egg-view-nunjucks --save

配置插件：

// config/plugin.js
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks'
};

配置视图：

// config/config.default.js
exports.view = {
  defaultViewEngine: 'nunjucks',
  mapping: {
    '.tpl': 'nunjucks'
  }
};

创建模板文件：

<!-- app/view/news/list.tpl -->
<!DOCTYPE html>
<html>
  <head>
    <title>新闻列表</title>
  </head>
  <body>
    <ul>
      {% for item in list %}
        <li>{{ item.title }}</li>
      {% endfor %}
    </ul>
  </body>
</html>

5. 服务层(Service)

Service 是业务逻辑的主要存放地：

// app/service/news.js
const Service = require('egg').Service;

class NewsService extends Service {
  async list(page = 1) {
    // 这里可以写业务逻辑
    return [
      { id: 1, title: '新闻1' },
      { id: 2, title: '新闻2' }
    ];
  }
}

module.exports = NewsService;

在控制器中使用：

async list() {
  const newsList = await this.ctx.service.news.list();
  await this.ctx.render('news/list.tpl', { list: newsList });
}

6. 中间件开发

中间件用于处理请求前后的通用逻辑：

// app/middleware/robot.js
module.exports = options => {
  return async (ctx, next) => {
    const ua = ctx.get('user-agent');
    if (/Baiduspider/i.test(ua)) {
      ctx.status = 403;
      ctx.body = '禁止爬虫访问';
    } else {
      await next();
    }
  };
};

配置中间件：

// config/config.default.js
exports.middleware = ['robot'];

7. 单元测试

Egg.js 内置测试支持，创建测试文件：

// test/app/controller/home.test.js
const { app, assert } = require('egg-mock');

describe('测试首页', () => {
  it('应该返回200状态码', () => {
    return app.httpRequest()
      .get('/')
      .expect(200);
  });
});

运行测试：

npm test

项目结构规范

一个标准的 Egg.js 项目结构如下：

egg-project
├── app
│   ├── controller       // 控制器
│   ├── service          // 业务逻辑
│   ├── middleware       // 中间件
│   ├── public           // 静态资源
│   └── view             // 模板文件
├── config
│   ├── config.default.js // 默认配置
│   └── plugin.js        // 插件配置
├── test                 // 测试目录
└── package.json