Egg：阿里企业级 Node.js 框架快速初始化与开发指南

项目官方信息

项目背景与核心特性

Egg 是阿里系开源的企业级 Node.js 框架，官方 README 用一条横幅图展示项目形象，并在头部用一组徽章展示工程状态：NPM 版本号、包质量评分、月度下载量、Node.js 版本要求、FOSSA 许可证扫描、CI 构建状态、测试覆盖率、已知漏洞数以及 Open Collective 赞助与捐赠者。从这些徽章可以看到，Egg 是一个下载量大、持续维护、质量门禁完整的企业级框架，而不是停更的个人项目。

官方 README 列出的核心特性共四项，完整翻译如下：

• 内置多进程管理：框架原生提供多进程模型管理能力，开发者不必自己折腾 Node.js 进程的 fork、重启与负载分配；
• 插件系统：高度可扩展的插件机制，把日志、数据库、鉴权等通用能力沉淀为可复用插件；
• 框架定制：支持在 Egg 之上做深度框架定制，团队可以基于 Egg 封装出符合自己规范的上层框架；
• 丰富的插件生态：官方维护了大量插件，覆盖常见业务场景。

下面把四项特性再展开说明。内置多进程管理：Node.js 是单线程事件驱动模型，直接在生产跑单个进程无法利用多核 CPU，也难以在进程异常时自动恢复，Egg 把多进程管理做成框架内置能力，开发者无需自己写 cluster 方案即可获得多进程服务与故障自愈，这是它区别于纯库类框架的工程化卖点。插件系统：框架把日志、数据库访问、鉴权、Session 等通用能力设计成插件，业务通过配置开启即可使用，而不需要在每个项目里复制粘贴一套中间件。框架定制：Egg 允许在它之上再封装一层团队自己的框架，把团队的目录规范、中间件、配置约定固化进去，保证同一公司多个项目结构一致，这是它面向大型团队协作的设计取向。丰富的插件生态：配合插件机制，官方与社区维护了覆盖常见业务场景的插件库，新业务可以快速拼装出所需能力，而不是从零写起。

项目质量门禁

Egg 在 README 头部展示了一整套公开徽章，每一项都对应一个可核查的工程事实，这里逐一完整翻译说明。NPM version 徽章显示当前发布到 npm 的最新版本号；NPM quality 徽章给出包质量评分；NPM download 徽章展示月度下载量，反映社区真实使用规模；Node.js Version 徽章标明框架要求的 Node.js 版本；FOSSA 徽章做许可证合规扫描；Continuous Integration 徽章指向主 CI 流水线；Test coverage 徽章展示测试覆盖率；Known Vulnerabilities 徽章由 Snyk 持续扫描已知漏洞；Open Collective 徽章展示赞助方与捐赠者名单。这组徽章说明 Egg 是一个长期维护、下载量大、有完整质量门禁的成熟框架，而不是个人玩具项目。

环境要求

官方 README 在快速开始命令下方给出了明确的版本要求：Node.js 版本必须 >= 22.18.0；同时建议生产环境使用处于支持期的 LTS 版本的最新补丁版本，避免使用已经 EOL（End of Life）的 Node.js 版本。这意味着在新项目初始化之前，应先确认本机 Node.js 版本达标，可用 node -v 查看。之所以强调「最新补丁」，是因为 Node.js 每个 LTS 版本的早期补丁会修复若干 V8 与运行时 bug，生产应取最新补丁而不是任意 LTS 小版本。

快速开始（官方命令）

按照官方 README 给出的命令逐步执行即可从零初始化一个 Egg 示例应用：

$ npm install --global utoo@latest
$ mkdir showcase && cd showcase
$ ut create egg@beta
$ ut install
$ ut run dev
$ open http://localhost:7001

逐条说明：第一步全局安装 utoo 脚手架的最新版本；第二步新建一个 showcase 目录并进入；第三步用脚手架基于 egg@beta 模板生成项目；第四步安装项目依赖；第五步启动开发模式；最后在浏览器打开 http://localhost:7001 即可看到运行中的应用，Egg 的默认开发端口为 7001。整个流程从安装到跑起来只有六行命令，官方刻意把初始化路径压到最短，让新用户几分钟内就能看到第一个页面；如果 7001 端口被占用，先停掉占用进程再启动，README 未提供修改开发端口的参数，如需换端口请在项目配置中自行调整。

仓库结构（utoo monorepo）

官方 README 说明，这个项目以 utoo monorepo 的方式组织，包含以下几个包：

• packages/egg —— Egg 框架主包；
• examples/helloworld-commonjs —— CommonJS 写法的示例应用；
• examples/helloworld-typescript —— TypeScript 写法的示例应用；
• site —— 文档网站。

整个 monorepo 使用 utoo catalog 模式做集中依赖管理，保证所有子包的依赖版本一致，避免仓库内出现版本漂移。

常用开发命令

官方 README 给出的 monorepo 开发命令如下：

# 安装所有包的依赖
ut install

# 构建所有包
ut run build

# 运行所有包的测试
ut run test

# 只运行某个包的命令
ut --filter=egg run test
ut --filter=@examples/helloworld-typescript run dev
ut --filter=site run dev

其中 ut --filter=<包名> 用于在 monorepo 中精确过滤出单个包执行命令，例如单独跑主包测试、单独启动 TypeScript 示例应用、单独启动文档站点。

本地外部服务依赖

官方 README 说明：部分 DAL、ORM、Redis 以及生态基准测试路径需要本地的 MySQL 与 Redis 服务。这是因为 Egg 仓库不仅包含框架本体，还包含 DAL（数据访问层）、ORM、Redis 插件、Session 插件等大量周边模块，跑这些模块的测试必须有真实数据库与缓存可用。在干净的机器上跑这些测试之前，先启动与仓库对齐的 Docker 服务：

ut run dev:services:start

这条命令会启动 MySQL 8 与 Redis 7，版本与主 CI 服务保持一致，并自动创建本地 DAL/ORM/e2e 夹具所用的数据库，具体包括：test、apple、banana、test_runtime_datasource、test_runtime_dao、test_dal_plugin、test_dal_standalone、cnpmcore 与 cnpmcore_unittest。

配套的状态管理命令：

ut run dev:services:status
ut run dev:services:stop
ut run dev:services:reset

默认宿主机端口为 MySQL 127.0.0.1:3306、Redis 127.0.0.1:6379。如果其中某个端口已被占用，启动命令会在改动容器之前中止，此时你可以继续使用与 CI 兼容的已有服务，或者停掉它再重新执行启动命令。宿主机端口可以通过环境变量 EGG_DEV_SERVICES_MYSQL_PORT 与 EGG_DEV_SERVICES_REDIS_PORT 修改；但要注意，完整的 DAL/ORM/Redis 本地测试路径仍然按默认宿主机端口设计。

镜像版本也支持通过环境变量覆盖，用于兼容性检查：

EGG_DEV_SERVICES_MYSQL_IMAGE=mysql:5.7 ut run dev:services:start
EGG_DEV_SERVICES_REDIS_IMAGE=redis:7 ut run dev:services:start

官方特别提醒：在切换 MySQL 镜像大版本之前（例如在 MySQL 8 与 MySQL 5.7 之间切换），要先执行 ut run dev:services:reset，因为 MySQL 数据目录不支持跨大版本降级。

README 还列出了当前仓库中硬编码的服务假设，供排查测试问题时对照：

• Redis 插件夹具（plugins/redis/test/fixtures/apps/**/config.*）使用 127.0.0.1:6379，该端口可用时原本被跳过的 Redis 插件测试才会执行；
• Session 的 Redis 夹具（plugins/session/test/fixtures/redis-session/config/config.default.js）使用 127.0.0.1:6379；
• DAL 运行时测试（tegg/core/dal-runtime/test/DataSource.test.ts 与 DAO.test.ts）使用本机 MySQL 的 3306 端口；
• DAL 模块夹具（tegg/plugin/dal/test/fixtures/apps/dal-app/modules/dal/module.yml 与 tegg/standalone/standalone/test/fixtures/dal-*/module.yml）使用本机 MySQL 的 3306 端口；
• ORM 夹具（tegg/plugin/orm/test/fixtures/prepare.js 与 tegg/plugin/orm/test/fixtures/apps/orm-app/config/config.default.ts）使用本机 MySQL 的 3306 端口。

文档与生态

官方 README 给出的文档与生态入口包括：官方文档站、插件列表、上层框架列表以及官方示例集合。插件与框架分别通过 GitHub topic egg-plugin、egg-framework 聚合，社区贡献的插件都可以在对应 topic 下检索到。这种按 topic 聚合的生态组织方式让使用者可以快速找到数据库、鉴权、消息队列等各类现成插件，而不必自己重复造轮子；基于 Egg 二次封装的上层框架则统一收录在 egg-framework topic 下，团队如果需要固化自己的项目规范，也可以参考这些框架的做法，站在社区经验上做封装。

贡献与赞助

官方维护了贡献者墙，展示所有参与过项目的贡献者。官方 README 建议：想反馈问题或提建议，先去 Issues 列表确认是否已有同类记录；想成为代码贡献者，请遵循贡献指南，并阅读仓库中的 AGENTS.md 了解日常开发约定。项目同时通过 Open Collective 接受企业赞助与个人捐赠，赞助方与捐赠者名单在徽章中持续展示，这些资金用于文档维护、社区活动与插件生态建设。

开源协议

Egg 基于 MIT 协议开源，这是最宽松的开源协议之一，允许商业项目自由使用、修改与再分发；许可证合规情况由 FOSSA 持续扫描维护，任何企业在合规评审时都可以直接引用 FOSSA 的扫描结果作为依据。

仓库结构再说明

官方 README 特别强调，这个项目不是一个孤立的 npm 包，而是一个完整的 utoo monorepo：packages/egg 是框架主包本体；examples/helloworld-commonjs 与 examples/helloworld-typescript 分别提供 CommonJS 与 TypeScript 两种写法的示例应用，方便不同技术栈的开发者对照学习；site 是官方文档网站本身，文档与代码在同一个仓库里演进。整个 monorepo 使用 utoo catalog 模式集中管理依赖，确保所有子包依赖版本一致，这是多包仓库避免版本碎片化的关键工程手段。

常见问题 FAQ

问：运行 Egg 对 Node.js 版本有什么要求？ 答：README 明确要求 Node.js >= 22.18.0；生产环境建议使用处于支持期的 LTS 版本的最新补丁版，不要用已 EOL 的旧版本。

问：官方推荐的项目初始化命令是什么？ 答：全局装 utoo@latest 后，依次执行 ut create egg@beta、ut install、ut run dev，然后打开 http://localhost:7001。

问：跑测试时连不上 MySQL/Redis 怎么办？ 答：先执行 ut run dev:services:start 启动与 CI 对齐的 MySQL 8 和 Redis 7；默认端口是 3306 与 6379，被占用时用 EGG_DEV_SERVICES_MYSQL_PORT、EGG_DEV_SERVICES_REDIS_PORT 改端口，但注意完整测试路径仍按默认端口设计。

问：测试里连的是哪个数据库？ 答：README 列出了自动创建的夹具数据库清单：test、apple、banana、test_runtime_datasource、test_runtime_dao、test_dal_plugin、test_dal_standalone、cnpmcore、cnpmcore_unittest。

问：切换 MySQL 5.7 与 8 镜像要注意什么？ 答：先用 EGG_DEV_SERVICES_MYSQL_IMAGE=mysql:5.7 之类的环境变量覆盖镜像，切换前必须先执行 ut run dev:services:reset，因为 MySQL 数据目录不支持跨大版本降级。

问：项目采用什么开源协议？ 答：MIT 协议，商用友好。

问：仓库里同时提供了哪几种示例？ 答：README 列出 monorepo 内三个示例与站点：主框架包 packages/egg、CommonJS 示例 examples/helloworld-commonjs、TypeScript 示例 examples/helloworld-typescript，以及文档网站 site，刚入门的开发者可以按自己的技术栈挑对应示例对照学习。

问：monorepo 的依赖是怎么管理的？ 答：README 说明整个仓库使用 utoo catalog 模式集中管理依赖，保证所有子包版本一致，避免多包仓库常见的版本漂移问题。

问：如何只给某个子包跑测试？ 答：用 ut --filter=<包名> run test，例如 ut --filter=egg run test；同理可以 ut --filter=@examples/helloworld-typescript run dev 单独启动 TypeScript 示例，或 ut --filter=site run dev 单独启动文档站点。

问：本地服务的 MySQL/Redis 版本为什么必须对齐 CI？ 答：README 明确 ut run dev:services:start 启动的是 MySQL 8 与 Redis 7，与主 CI 服务版本保持一致；版本不一致可能导致本地测试与 CI 结果不一致，排障时先确认本地服务版本。

问：想给 Egg 提代码要遵循什么流程？ 答：README 建议先在 Issues 确认问题，再按贡献指南提交，并阅读仓库 AGENTS.md 了解日常开发约定。

问：Egg 目前的维护状态如何？ 答：从 README 徽章看，项目持续有 CI 流水线、测试覆盖率统计、Snyk 漏洞扫描与 Open Collective 赞助在运转，属于长期活跃维护的成熟项目。

问：Egg 适合什么类型的项目？ 答：README 定位它为企业级 Node.js 框架，主打内置多进程管理、插件体系与框架定制，适合中大型团队协作的 Web 服务项目，团队可以基于它封装出符合内部规范的上层框架。

问：Egg 的 npm 包怎么找？ 答：官方包就是 npmjs.org/package/egg，版本号、月度下载量与包质量评分都在 README 头部徽章中实时展示，新项目初始化时通过 utoo 脚手架拉取 egg@beta 模板即可，不必手动查 npm 版本号。

跳转链接

• 项目仓库：github.com/eggjs/egg
• 官方文档：eggjs.org
• 插件生态：egg-plugin topic
• 上层框架：egg-framework topic
• 官方示例：eggjs/examples
• 问题反馈：Issues
• 贡献指南：CONTRIBUTING.md
• 赞助支持：Open Collective