企业官网建设流程全解析

• 后端
• Web框架

应用启动阶段是 Egg 框架承接外部流量的关键节点：框架只有完成配置加载、插件装配与用户初始化逻辑后，才会对外提供请求服务。本文围绕 docs/source/en/basics/app-start.md 所阐述的启动自定义机制，完整讲解app.js入口文件与beforeStart生命周期钩子的用法、执行语义与超时保护，并结合本仓库 lib/egg.js、lib/application.js 等核心源码与测试夹具，给出可复制、可落地的初始化方案。

阅读完本文，你将掌握：如何在 Egg 应用中通过app.js挂载全局属性与异步初始化逻辑、beforeStart的阻塞式执行语义、workerStartTimeout超时机制的底层实现，以及启动失败时的日志定位方法。

为什么需要启动自定义

在 Egg 中，应用的生命周期包含"启动前初始化 → 就绪（ready）→ 对外服务"三个阶段。文档明确指出：

When the application starts up, we often need to set up some initialization logic. The application bootstraps with those specific configurations. It is in a healthy state and be able to take external service requests after those configurations successfully applied. Otherwise, it failed.

也就是说，只有启动阶段的初始化逻辑全部成功执行完毕，应用才会进入健康状态并开始接收外部请求；初始化失败则视为启动失败。这一设计保证了业务上线前的前置条件（如缓存预热、远程配置拉取、数据源连接）必然就绪，避免"带病上线"。

Egg 为这一需求提供了统一的入口文件app.js，它位于应用根目录，框架会判断该文件是否存在，若存在则执行其中导出的初始化函数。相关加载行为由 lib/loader/app_worker_loader.js 中的loadCustomApp()触发（源码中对应load()流程内app > plugin优先级的loadCustomApp()步骤），该文件遵循"只导出一个函数"的约定：

// app.js module.exports = app => { // 启动初始化逻辑 };

入口函数接收app实例作为唯一参数。此时app已经完成配置加载与插件装配，你可以访问app.config、app.logger、app.curl、app.messenger等全部应用级能力（详见 docs/source/en/basics/objects.md）。

beforeStart：阻塞式异步初始化

beforeStart是启动自定义的核心 API，它注册的回调会被框架同步等待：只有所有beforeStart回调执行完成，应用才会标记为 ready 并开始监听端口、对外服务。文档给出的经典场景是"启动期间从远程接口加载全国城市列表供 Controller 使用"：

// app.js module.exports = app => { app.beforeStart(function* () { // 应用会等待这个函数执行完成才启动 app.cities = yield app.curl('http://example.com/city.json', { method: 'GET', dataType: 'json', }); }); };

执行语义

• Generator 函数：function* ()配合yield实现异步等待。框架在等待期间不会继续启动流程，因此app.cities在应用就绪时必然已赋值。
• async/await 同样受支持：仓库测试夹具 test/fixtures/apps/async-app/app.js 展示了 async 函数写法：

module.exports = app => { app.beforeStart(async () => { await Promise.resolve(); await app.runSchedule('async'); app.beforeStartExectuted = true; }); app.beforeClose(async () => { await Promise.resolve(); app.beforeCloseExecuted = true; }); };

可见 async 函数与 Generator 两种异步风格均可用于beforeStart，并且beforeClose（关闭前钩子）采用同样签名，可用于优雅退出前的资源清理。beforeStart的类型声明可在 index.d.ts 中确认：beforeStart(scrope: () => void): void;。

在 Controller 中使用

由于cities直接挂载在全局app实例上，任何持有app引用的位置都能访问，Controller 中通过ctx.app获取：

// app/controller/city.js module.exports = function* (ctx) { // ctx.app.cities 在启动期间已经加载，可以直接使用 ctx.body = ctx.app.cities; };

需要说明的是，挂载在app上的属性属于进程内共享数据（Worker 进程级别）。Egg 多进程模型下每个 Worker 都会执行自己的app.js初始化，因此各 Worker 各自持有初始化结果，不会跨进程自动同步；若需要跨进程共享数据，应结合app.cluster（参见 lib/egg.js 的 cluster-client 封装）或外部存储实现。

超时保护：workerStartTimeout

文档末尾的注意点至关重要：

Note: When the framework executes the lifecycle methodbeforeStart, do not run time-consuming operation. The framework enables aTimeoutsetting by default when it starts up.

框架对启动过程设有默认超时检测，避免初始化逻辑卡死导致应用永远无法就绪。该机制在 lib/egg.js 中实现：

_setupTimeoutTimer() { const startTimeoutTimer = setTimeout(() => { this.coreLogger.error(`${this.type} still doesn't ready after ${this.config.workerStartTimeout} ms.`); this.emit('startTimeout'); }, this.config.workerStartTimeout); this.ready(() => clearTimeout(startTimeoutTimer)); }

工作原理

1. 构造EggApplication时启动一个定时器，时长取this.config.workerStartTimeout；
2. 若应用在超时前完成 ready（即所有beforeStart等就绪回调执行完毕），ready()会清除该定时器，启动正常完成；
3. 若超时仍未 ready，框架向coreLogger输出错误日志still doesn't ready after ... ms，并触发startTimeout事件，同时会process.exit(1)终止进程，由 Master 按策略处理（相关测试夹具 test/fixtures/apps/app-start-timeout/config/config.default.js 将超时缩短为1000ms以验证该路径）。

默认值与调优

默认配置位于 config/config.default.js：

/** * emit `startTimeout` if worker don't ready after `workerStartTimeout` ms * @member {Number} Config.workerStartTimeout */ config.workerStartTimeout = 10 * 60 * 1000;

即默认 10 分钟。在应用config/config.default.js（或环境配置）中覆盖即可：

// config/config.default.js exports.workerStartTimeout = 30 * 1000; // 30 秒

调优建议：

• 初始化逻辑涉及外部依赖（远程接口、数据库连接）时，应显式设置合理的超时时间，避免默认 10 分钟过长导致故障发现延迟；
• 超时时间应大于初始化逻辑的最坏耗时，但不宜过大；同时建议在beforeStart内部为外部调用设置更短的请求超时（app.curl的timeout选项，毫秒为单位），让失败快速暴露。

启动失败的表现与定位

当beforeStart内抛错或超时未就绪时：

• 错误信息写入coreLogger，即egg-web日志文件（$HOME/logs/{appname}/egg-web.log）；
• 日志中会出现形如application still doesn't ready after 30000 ms.的记录（this.type在 Application 与 Agent 中分别为application与agent，见 lib/application.js 与 lib/agent.js）；
• 进程退出后，Master 会根据配置决定是否重启（如app.die场景），相关行为可参考 test/fixtures/apps/app-die 测试夹具。

启动初始化的典型实践

预热匿名 Context：提前加载 Service

有些初始化逻辑需要访问ctx上的能力（如ctx.service）。由于beforeStart回调只拿到app，可以借助app.createAnonymousContext()创建一个脱离请求的匿名 Context（实现见 lib/egg.js）。docs/source/zh-cn/basics/objects.md 中的示例：

// app.js module.exports = app => { app.beforeStart(function* () { const ctx = app.createAnonymousContext(); // preload before app start yield ctx.service.posts.load(); }); };

与其他生命周期配合

• beforeClose：注册应用关闭前的清理逻辑（关闭连接、刷新缓冲等），签名与beforeStart一致，仓库在 lib/egg.js 内部注册了日志器关闭与 Messenger 清理，用户可在app.js中追加自己的清理逻辑。
• agent.beforeStart：在 Agent 进程（lib/agent.js）中同样存在beforeStart，用于启动阶段初始化 Agent 侧逻辑，测试夹具 test/fixtures/apps/cluster_mod_app/agent.js 中agent.beforeStart(function*(){ ... })即为佐证。

避免耗时操作的工程化建议

结合超时机制，beforeStart中的操作应遵循：

1. 只做必要的前置初始化：如拉取配置、建立连接、预热缓存，不做与对外服务无关的重计算；
2. 为每个外部调用设置超时：app.curl(url, { timeout: 3000, dataType: 'json' })；
3. 可降级的数据延迟加载：若数据非关键路径，可在首次请求时惰性加载并缓存，而不是阻塞启动；
4. 善用日志：在初始化步骤间输出app.logger.info，便于在egg-web.log中定位卡点（Worker 就绪时序可通过 lib/egg.js 中的dumpTiming()输出到run/{type}_timing_{pid}.json辅助分析）。

小结

Egg 的启动自定义机制可以总结为一条清晰的链路：应用根目录的app.js是唯一入口 → 导出的函数接收app→ 用beforeStart注册阻塞式异步初始化 → 全部完成才 ready → 超时由workerStartTimeout兜底。这一设计既保证了"初始化完成才对外服务"的一致性，又通过超时检测防止应用永久卡死。

实践上只需记住两个关键点：在beforeStart中做必要的数据预加载并通过app挂载共享；不要在其中执行耗时操作，并为整个启动过程配置合理的workerStartTimeout。相关源码可在 lib/egg.js、lib/application.js 与 config/config.default.js 中进一步研读。

• 后端
• Web框架