1. 為什么 Egg.js 4.0 值得后端團隊重新評估Egg.js 4.0 是阿里開源的企業(yè)級 Node.js 框架在 2025 年的一次大版本重構(gòu)核心變化可以概括成三件事全 TypeScript 重寫、DDD 模塊化架構(gòu)原生支持、AI 能力MCP / Agent內(nèi)置。它適合誰適合正在用 Egg.js 2.x/3.x 維護中大型單體、又想把架構(gòu)往領(lǐng)域驅(qū)動方向遷移的 Node.js 后端團隊也適合準(zhǔn)備做 AI Agent 服務(wù)端、但不想從零搭一套通信協(xié)議和編排層的團隊。我所在的團隊維護著一套 3.x 的訂單系統(tǒng)二十多個 controller 擠在一個目錄里路由靠router.js手寫類型提示基本靠注釋。改一個字段要全局搜新人上手兩周還在問「這個 service 在哪注冊的」。Egg.js 4.0 的 tegg 模板把這些問題拆成了三塊裝飾器聲明路由和依賴注入、modules 目錄做領(lǐng)域隔離、MCP 裝飾器直接暴露 AI 工具。下面按「搭骨架 → 配 TS → 接 AI → 驗證 → 排障」的順序走一遍命令和配置都能直接復(fù)制。2. TaoToken 前置給 AI 能力準(zhǔn)備一個可調(diào)用的模型入口Egg.js 4.0 的 Agent 和 MCP 工具最終要落到一個能對話的模型上。企業(yè)內(nèi)網(wǎng)環(huán)境里直接調(diào)外部模型接口往往卡在鑒權(quán)和網(wǎng)絡(luò)策略上所以我會先用 TaoToken 把模型調(diào)用這一層固定下來再讓框架去接。TaoToken 是一個兼容 OpenAI 接口規(guī)范的模型調(diào)用平臺官網(wǎng)在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是給你一個統(tǒng)一的 base_url 和 key框架側(cè)只認這兩個值換模型不用改業(yè)務(wù)代碼。操作路徑很直接進控制臺 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 創(chuàng)建 API Key然后在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 里復(fù)制出來。想先確認模型通不通用模型對話頁 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 發(fā)一條測試消息即可。接入細節(jié)查文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 只放服務(wù)端環(huán)境變量不要寫進config.default.ts提交到倉庫。Egg.js 的config目錄默認會被打包硬編碼等于泄露。3. 可復(fù)制配置Egg.js 4.0 項目骨架 DDD 分層 TypeScript3.1 初始化 tegg 模板# 創(chuàng)建 DDD TS 風(fēng)格的項目 npx create-eggbeta --template tegg egg4-ddd-demo cd egg4-ddd-demo npm install生成后的目錄結(jié)構(gòu)大致是這樣modules是領(lǐng)域核心egg4-ddd-demo/ ├── config/ │ ├── config.default.ts │ └── plugin.ts ├── modules/ │ └── user/ │ ├── controller/ │ │ └── UserController.ts │ ├── service/ │ │ └── UserService.ts │ ├── module.ts │ ├── module.yml │ └── package.json ├── tsconfig.json └── package.json3.2 TypeScript 配置要點tsconfig.json里和 tegg 裝飾器相關(guān)的幾項必須打開否則運行時報「裝飾器元數(shù)據(jù)缺失」{ compilerOptions: { target: ES2022, module: commonjs, experimentalDecorators: true, emitDecoratorMetadata: true, strict: true, esModuleInterop: true, skipLibCheck: true, outDir: dist, baseUrl: ., paths: { /*: [modules/*] } }, include: [modules/**/*.ts, config/**/*.ts] }experimentalDecorators和emitDecoratorMetadata是裝飾器注入的命門strict打開后類型提示才完整。paths里的別名讓跨模塊引用寫成/user/service/UserService比相對路徑../../清爽。3.3 DDD 分層controller / service / module 各管什么一個領(lǐng)域模塊內(nèi)部按職責(zé)分三層以 user 為例// modules/user/service/UserService.ts import { SingletonProto, Inject } from eggjs/tegg; SingletonProto() export class UserService { async findById(id: string): Promise{ id: string; name: string } { // 真實項目里這里走 repository示例直接返回 return { id, name: user-${id} }; } }// modules/user/controller/UserController.ts import { HTTPController, HTTPMethod, HTTPMethodEnum, Inject } from eggjs/tegg; import { UserService } from ../service/UserService; HTTPController({ path: /api/user }) export class UserController { Inject() userService: UserService; HTTPMethod({ method: HTTPMethodEnum.GET, path: /:id }) async detail(ctx: any) { const user await this.userService.findById(ctx.params.id); return { code: 0, data: user }; } }SingletonProto()聲明單例服務(wù)Inject()自動注入不用再寫app.service.user。HTTPController和HTTPMethod把路由聲明在業(yè)務(wù)文件里router.js可以徹底刪掉。3.4 接入 AIMCP 裝飾器暴露工具Egg.js 4.0 內(nèi)置 MCP Client/Server用裝飾器就能把服務(wù)端能力暴露給 Agent// modules/ai/controller/McpController.ts import { MCPController, MCPPrompt, MCPTool } from eggjs/tegg-mcp; MCPController() export class McpController { MCPPrompt() async welcome() { return { content: 我是訂單助手可以幫你查訂單狀態(tài) }; } MCPTool() async queryOrder() { return { toolName: query-order, desc: 按訂單號查詢狀態(tài), parameters: [ { name: orderId, type: string, required: true, desc: 訂單號 }, ], }; } }模型側(cè)要調(diào)用的地址和 key通過環(huán)境變量注入# .env不要提交 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的key// config/config.default.ts export default { ai: { baseURL: process.env.TAOTOKEN_BASE_URL, apiKey: process.env.TAOTOKEN_API_KEY, model: gpt-4o-mini, }, };4. 驗證請求從啟動到 AI 工具調(diào)用成功4.1 啟動并檢查模塊加載npm run dev啟動日志里會打印已加載的 module 列表確認user和ai都在。如果某個 module 沒出現(xiàn)多半是module.yml里name和目錄名不一致。4.2 驗證普通 HTTP 接口curl http://127.0.0.1:7001/api/user/42預(yù)期返回{ code: 0, data: { id: 42, name: user-42 } }這一步通了說明裝飾器路由和依賴注入都正常。4.3 驗證模型連通性先用 curl 直接打 TaoToken 的接口確認 key 和 base_url 沒問題curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回復(fù) ok}] }返回里有choices[0].message.content就說明模型側(cè)通了。這一步單獨做的好處是后面 Agent 報錯時能快速區(qū)分是框架問題還是模型入口問題。4.4 驗證 MCP 工具被 Agent 識別啟動后訪問 MCP 服務(wù)端點tegg 默認掛在/mcp下用 MCP 客戶端或框架自帶的調(diào)試頁查看工具列表應(yīng)該能看到query-order。如果工具沒注冊上檢查MCPTool()所在類是否被MCPController()包裹以及該 module 是否在module.yml里聲明。5. 本篇常見錯排查5.1 裝飾器報錯「Unable to resolve signature」現(xiàn)象Inject()下面出現(xiàn)紅色波浪線運行時報Cannot read property userService of undefined。原因tsconfig.json缺emitDecoratorMetadata或者experimentalDecorators被其他配置覆蓋。處理確認兩項都為true刪掉dist重新npm run dev。如果用了ts-node加--compiler-options顯式指定。5.2 module 加載失敗「module.yml not found」現(xiàn)象啟動日志報某個 module 跳過。原因module.yml里的name字段和目錄名不一致或者package.json的name沒寫。處理module.yml保持name: userpackage.json里name: user兩者和目錄名三者一致。5.3 MCP 工具調(diào)用返回 401現(xiàn)象Agent 能列出工具但實際調(diào)用時報鑒權(quán)失敗。原因TAOTOKEN_API_KEY沒注入到進程或者.env沒被加載。處理Egg.js 默認不讀.env用dotenv在config.default.ts頂部import dotenv/config或者直接在啟動命令前export。確認process.env.TAOTOKEN_API_KEY有值再啟動。5.4 舊項目升級后路由 404現(xiàn)象裝了eggjs/tegg-plugin和eggjs/tegg-config后老router.js里的路由失效。原因tegg 接管路由后舊式router.get()聲明和裝飾器路由的加載順序有沖突。處理升級期兩者可以共存但要確保plugin.ts里 tegg 插件在router之前啟用。逐步把router.js里的條目遷到裝飾器遷完再刪。5.5 類型提示不生效現(xiàn)象IDE 里this.userService沒有補全。原因paths別名沒配或者 IDE 用的 TS 版本低于 5.0。處理tsconfig.json的paths加上/*重啟 TS ServerVS Code 里CtrlShiftP→ Restart TS Server。6. 長期編碼與 Agent 場景的下一步如果只是驗證模型通不通用模型對話頁發(fā)一條消息就夠了。但要把 Egg.js 4.0 的 Agent 能力真正落到日常編碼和長期運行的服務(wù)里建議走 Coding Plan把模型調(diào)用額度、并發(fā)和 Agent 編排統(tǒng)一管起來https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。我自己的做法是本地開發(fā)用模型對話頁快速試 promptCI 里用 Coding Plan 的 key 跑 Agent 回歸生產(chǎn)環(huán)境把 key 放密鑰管理服務(wù)Egg.js 側(cè)只讀環(huán)境變量。這樣框架升級、模型切換、額度調(diào)整三件事互不干擾。