Egg.js 简介与快速开始

🎯 引言

学完这篇文章，你能说清楚 Egg.js 是什么、它和 Express、Koa 有什么不同，还能用官方脚手架在自己的电脑上创建一个 Egg 项目，启动服务并写出第一个接口。这是我们进入企业级 Node.js 开发的第一步。

🧱 什么是 Egg.js

Egg.js 是一个基于 Koa 的 Node.js Web 开发框架，由阿里巴巴团队开源并维护，常用于企业级应用的开发。

它的核心理念是约定优于配置：目录放什么文件、文件怎么命名、代码挂在哪个对象上，框架都约定好了。你只需要把代码写到约定的位置，Egg 会自动加载并组装起来。

✨ 为什么选择 Egg.js

Express 和 Koa 的特点是自由灵活，一个文件就能启动服务。但自由也意味着：十个人能写出十种目录结构，团队协作时风格难以统一。

Egg.js 的思路正好相反，它把常用的工程实践固化成了约定：

• 目录结构统一：路由、控制器、业务逻辑、中间件各有固定位置，看任何 Egg 项目都不会迷路。
• 内置能力丰富：安全校验、请求体解析、日志等常用能力开箱即用，不用自己挑库组装。
• 适合团队协作：大家的写法天然一致，新成员上手成本低。

可以打个比喻：Express、Koa 像一块空地，想怎么盖都行；Egg 像精装修的公寓，格局已经定好，拎包入住就能干活。

🛠 用脚手架创建项目

Egg 官方提供了脚手架工具，一条命令就能生成标准项目。本文及本课程基于 Node.js v22 LTS、egg 3.x（当前为 3.34.0）编写和验证。

打开终端，进入你想放项目的目录，执行：

npm init egg --type=simple

脚手架会依次询问几个问题：选择模板类型（simple）、项目名称、项目描述、作者等。学习阶段一路按回车使用默认值即可，等待依赖安装完成。

完成后进入项目目录并启动：

cd egg-example
npm run dev

看到 egg started on http://127.0.0.1:7001 就说明启动成功了。浏览器访问 http://127.0.0.1:7001，页面会显示 hi, egg。

🧱 认识目录结构

打开生成的项目，先看几个核心目录和文件：

egg-example
├── app
│   ├── router.js          # 路由：定义 URL 和处理逻辑的对应关系
│   ├── controller         # 控制器：接收请求、返回响应
│   ├── service            # 业务逻辑层：处理具体业务和数据
│   ├── middleware         # 自定义中间件
│   └── extend             # 框架扩展：给内置对象添加方法
├── config
│   ├── config.default.js  # 默认配置
│   └── plugin.js          # 插件配置
└── package.json

这就是“约定优于配置”的直接体现：文件放在约定位置、按约定方式导出，Egg 启动时会自动加载它们，不需要手动 require 组装。

🛠 第一个接口

脚手架自带了一个示例。打开 app/controller/home.js：

const { Controller } = require('egg');

class HomeController extends Controller {
    async index() {
        const { ctx } = this;
        ctx.body = 'hi, egg';
    }
}

module.exports = HomeController;

再看路由 app/router.js：

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

两处配合的含义是：访问 GET / 时，交给 app/controller/home.js 里的 index 方法处理，用 ctx.body 返回内容。

我们把它改成一个 JSON 接口试试：

const { Controller } = require('egg');

class HomeController extends Controller {
    async index() {
        const { ctx } = this;
        ctx.body = {
            message: '你好，Egg.js',
        };
    }
}

module.exports = HomeController;

保存后刷新浏览器，就能看到返回的 JSON 了。给 ctx.body 赋一个对象，Egg 会自动转成 JSON 返回，不用手动设置 Content-Type。

🧾 小节总结

• Egg.js 是基于 Koa 的 Node.js 框架，由阿里巴巴团队开源，核心理念是约定优于配置。
• 相比 Express、Koa 的自由灵活，Egg 用统一约定换取团队协作的一致性，并内置了安全、日志等常用能力。
• 用 npm init egg --type=simple 创建项目，npm run dev 启动，默认端口 7001。
• 核心目录：app/router.js 配路由，app/controller 处理请求，app/service 写业务逻辑，config 放配置。
• 给 ctx.body 赋值即可返回响应，赋对象会自动转成 JSON。

❓ 知识问答

Q1：Egg.js 和 Koa 是什么关系？

Egg 底层基于 Koa，可以把它理解为“定好规范、装好配件的 Koa”。Koa 的 ctx、中间件、洋葱模型在 Egg 里都适用。

Q2：学会 Express 或 Koa 了，还有必要学 Egg 吗？

小项目用 Express、Koa 很顺手；多人协作的中大型项目里，Egg 的统一约定能减少大量沟通成本。企业招聘中 Egg 也是常见要求之一。

Q3：为什么 Egg 代码用 CommonJS 而不是 ESM？

这是 Egg 官方的历史约定，框架的自动加载机制基于 CommonJS 实现。跟随官方示例用 require 和 module.exports 即可，不影响学习。

Q4：改了代码需要重启服务吗？

npm run dev 启动的开发模式会监听文件变化并自动重启，保存文件后直接刷新浏览器即可。

🧪 小练习

在 home.js 中新增一个 info 方法，返回你的姓名和学习日期，并在 router.js 中把它挂到 GET /info 上。

class HomeController extends Controller {
    async index() {
        // 原有代码保持不变
    }

    async info() {
        const { ctx } = this;
        // 请在这里编写代码
    }
}

module.exports = app => {
    const { router, controller } = app;
    router.get('/', controller.home.index);
    // 请在这里编写代码
};

🎉 恭喜你已经跑通了第一个 Egg.js 项目！下一篇我们深入学习路由与 Controller，看看如何接收各种请求参数并返回规范的响应。