快捷導(dǎo)航

EggJS 項(xiàng)目中使用 TypeScript 的完整指南

更新時(shí)間：2026年05月26日 10:14:57 作者：平鈺垚Zebediah

本文將介紹在 EggJS 框架中集成和使用 TypeScript,幫助開(kāi)發(fā)者提升開(kāi)發(fā)效率和代碼質(zhì)量,文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧

前言

TypeScript 作為 JavaScript 的超集，通過(guò)靜態(tài)類(lèi)型檢查、智能提示和友好的 IDE 支持，為大型企業(yè)級(jí)應(yīng)用開(kāi)發(fā)帶來(lái)了顯著優(yōu)勢(shì)。本文將詳細(xì)介紹如何在 EggJS 框架中集成和使用 TypeScript，幫助開(kāi)發(fā)者提升開(kāi)發(fā)效率和代碼質(zhì)量。

為什么選擇 TypeScript

TypeScript 為 JavaScript 帶來(lái)了類(lèi)型系統(tǒng)，主要優(yōu)勢(shì)包括：

靜態(tài)類(lèi)型檢查：在編譯階段就能發(fā)現(xiàn)潛在的類(lèi)型錯(cuò)誤
智能提示：IDE 能提供更準(zhǔn)確的代碼補(bǔ)全和文檔提示
更好的可維護(hù)性：類(lèi)型注解使代碼更易于理解和維護(hù)
漸進(jìn)式采用：可以逐步將現(xiàn)有 JavaScript 項(xiàng)目遷移到 TypeScript

快速開(kāi)始

初始化項(xiàng)目

使用以下命令快速創(chuàng)建一個(gè) TypeScript 版本的 EggJS 項(xiàng)目：

mkdir showcase && cd showcase
npm init egg --type=ts
npm i
npm run dev

這個(gè)命令會(huì)創(chuàng)建一個(gè)簡(jiǎn)單的 TypeScript 示例項(xiàng)目，包含基本的控制器、服務(wù)和路由配置。

項(xiàng)目結(jié)構(gòu)

TypeScript 項(xiàng)目結(jié)構(gòu)與常規(guī) EggJS 項(xiàng)目類(lèi)似，主要區(qū)別在于：

文件后綴使用 .ts 而不是 .js
新增 typings 目錄存放類(lèi)型定義文件
需要 tsconfig.json 和 tslint.json 配置文件

典型目錄結(jié)構(gòu)如下：

showcase
├── app
│   ├── controller
│   │   └── home.ts
│   ├── service
│   │   └── news.ts
│   └── router.ts
├── config
│   ├── config.default.ts
│   ├── config.local.ts
│   ├── config.prod.ts
│   └── plugin.ts
├── test
│   └── **/*.test.ts
├── typings
│   └── **/*.d.ts
├── README.md
├── package.json
├── tsconfig.json
└── tslint.json

核心概念實(shí)現(xiàn)

控制器(Controller)

控制器示例：

import { Controller } from 'egg';
export default class HomeController extends Controller {
  public async index() {
    const { ctx, service } = this;
    const page = ctx.query.page;
    const result = await service.news.list(page);
    await ctx.render('home.tpl', result);
  }
}

路由(Router)

路由配置示例：

import { Application } from 'egg';
export default (app: Application) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};

服務(wù)(Service)

服務(wù)層示例：

import { Service } from 'egg';
export default class NewsService extends Service {
  public async list(page?: number): Promise<NewsItem[]> {
    return [];
  }
}
export interface NewsItem {
  id: number;
  title: string;
}

中間件(Middleware)

中間件實(shí)現(xiàn)示例：

import { Context } from 'egg';

export default function fooMiddleware() {
  return async (ctx: Context, next: any) => {
    await next();
  };
}

配置(Config)

配置管理是 TypeScript 集成中最復(fù)雜的部分，需要處理：

控制器和服務(wù)中的多層智能提示配置
配置合并時(shí)的類(lèi)型提示
自定義配置的類(lèi)型擴(kuò)展

配置示例：

import { EggAppInfo, EggAppConfig, PowerPartial } from 'egg';

export default (appInfo: EggAppInfo) => {
  const config = {} as PowerPartial<EggAppConfig>;

  config.keys = appInfo.name + '123456';
  config.view = {
    defaultViewEngine: 'nunjucks',
    mapping: {
      '.tpl': 'nunjucks',
    },
  };

  const bizConfig = {
    news: {
      pageSize: 30,
      serverUrl: 'https://hacker-news.firebaseio.com/v0',
    },
  };

  return {
    ...(config as {}),
    ...bizConfig,
  };
};

開(kāi)發(fā)工具鏈

ts-node 集成

egg-bin 內(nèi)置了 ts-node 支持，開(kāi)發(fā)時(shí)自動(dòng)加載和編譯 .ts 文件。只需在 package.json 中配置：

{
  "egg": {
    "typescript": true
  }
}

egg-ts-helper

由于 EggJS 的自動(dòng)加載機(jī)制，TypeScript 無(wú)法靜態(tài)分析依賴(lài)關(guān)系。我們使用 egg-ts-helper 工具自動(dòng)生成類(lèi)型定義文件：

{
  "egg": {
    "declarations": true
  },
  "scripts": {
    "dev": "egg-bin dev",
    "clean": "ets clean"
  }
}

該工具會(huì)自動(dòng)分析項(xiàng)目并生成 typings/{app,config}/ 下的類(lèi)型定義文件，開(kāi)發(fā)者不應(yīng)手動(dòng)修改這些文件。

測(cè)試與調(diào)試

單元測(cè)試

測(cè)試文件示例：

import assert from 'assert';
import { Context } from 'egg';
import { app } from 'egg-mock/bootstrap';
describe('test/app/service/news.test.js', () => {
  let ctx: Context;
  before(async () => {
    ctx = app.mockContext();
  });
  it('list()', async () => {
    const list = await ctx.service.news.list();
    assert(list.length === 30);
  });
});

調(diào)試配置

調(diào)試配置與常規(guī) JavaScript 項(xiàng)目類(lèi)似，通過(guò) sourcemap 可以準(zhǔn)確定位到 TypeScript 源代碼：

{
  "scripts": {
    "debug": "egg-bin debug",
    "debug-test": "npm run test-local -- --inspect"
  }
}

生產(chǎn)部署

構(gòu)建流程

生產(chǎn)環(huán)境建議將 TypeScript 編譯為 JavaScript 再運(yùn)行：

{
  "scripts": {
    "start": "egg-scripts start --title=egg-server-showcase",
    "tsc": "ets && tsc -p tsconfig.json",
    "ci": "npm run lint && npm run cov && npm run tsc"
  }
}

錯(cuò)誤堆棧

構(gòu)建時(shí)啟用 inlineSourceMap 確保線(xiàn)上錯(cuò)誤能映射到 TypeScript 源碼：

{
  "compilerOptions": {
    "inlineSourceMap": true
  }
}

常見(jiàn)問(wèn)題解答

生產(chǎn)環(huán)境 ts 文件未加載

npm start 使用 egg-scripts 運(yùn)行，而 ts-node 只集成在 egg-bin 中。生產(chǎn)環(huán)境建議先編譯再運(yùn)行：

npm run tsc
npm start

插件對(duì)象未加載類(lèi)型

可能原因：

插件缺少類(lèi)型定義：需要按規(guī)范為插件添加 index.d.ts
插件有類(lèi)型定義但未導(dǎo)入：需要顯式導(dǎo)入插件類(lèi)型聲明

臨時(shí)解決方案：

// typings/index.d.ts
import 'egg';
declare module 'egg' {
  interface Application {
    dashboard: any;
  }
}

tsconfig.json 中 paths 無(wú)效

tsc 不會(huì)轉(zhuǎn)換 import 路徑，運(yùn)行時(shí)需要額外工具處理路徑映射。建議使用模塊別名工具如 module-alias。

總結(jié)

本文詳細(xì)介紹了在 EggJS 項(xiàng)目中使用 TypeScript 的完整方案，包括項(xiàng)目結(jié)構(gòu)、核心概念實(shí)現(xiàn)、開(kāi)發(fā)工具鏈、測(cè)試調(diào)試和生產(chǎn)部署等方面。通過(guò)合理配置和工具支持，可以在 EggJS 項(xiàng)目中充分發(fā)揮 TypeScript 的優(yōu)勢(shì)，提升開(kāi)發(fā)體驗(yàn)和代碼質(zhì)量。

到此這篇關(guān)于EggJS 項(xiàng)目中使用 TypeScript 的完整指南的文章就介紹到這了,更多相關(guān)EggJS使用TypeScript 內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: