如何为Node/Express项目配置EJS与TypeScript类型检查？

EJS本身不原生支持TypeScript类型检查，但可以通过类型定义扩展+TypeScript配置来约束模板接收的上下文数据，同时辅助语法检查工具提升模板代码质量。以下是具体配置步骤：

1. 安装必要依赖 #

先安装EJS的TypeScript类型定义包：

npm install @types/ejs --save-dev

如果需要检查EJS模板的语法错误，可额外安装ejs-lint：

npm install ejs-lint --save-dev

2. 扩展EJS上下文类型 #

创建类型定义文件（比如src/types/ejs.d.ts），用来定义模板接收的全局/局部变量类型：

方式一：扩展EJS模块的render函数类型 #

declare module 'ejs' {
  // 定义所有模板共用的上下文数据类型
  interface TemplateLocals {
    user: {
      id: string;
      name: string;
      avatar?: string; // 可选属性
    };
    posts: Array<{
      title: string;
      content: string;
      createdAt: Date;
    }>;
    // 按需添加你的模板变量类型
  }

  // 重写EJS的render方法，强制使用定义的类型
  export function render(
    template: string,
    data: TemplateLocals,
    options?: Options,
  ): string;
}

方式二：扩展Express Response的render方法（更贴合Express场景） #

因为Express中常用res.render传递模板数据，直接扩展Response类型可以让TS在调用res.render时自动检查参数：

declare global {
  namespace Express {
    interface Response {
      render: (
        view: string,
        locals: {
          user: { id: string; name: string; avatar?: string };
          posts: Array<{ title: string; content: string; createdAt: Date }>;
          // 自定义你的模板变量类型
        },
        callback?: (err: Error | null, html: string) => void,
      ) => void;
    }
  }
}

// 必须导出空对象让TS识别为模块
export {};

3. 配置TypeScript编译选项 #

确保tsconfig.json中包含你的类型定义文件，并且开启严格类型检查：

{
  "compilerOptions": {
    "strict": true, // 开启严格类型检查，必选
    "typeRoots": ["./node_modules/@types", "./src/types"], // 指定类型文件目录
    "esModuleInterop": true
  },
  "include": ["src/**/*"], // 确保包含所有源码和类型文件
  "exclude": ["node_modules"]
}

4. （可选）封装类型安全的渲染函数 #

如果想进一步约束模板数据，可封装一个专用的渲染函数，避免直接调用res.render时出错：

import { Response } from 'express';

// 复用之前定义的TemplateLocals类型
type TemplateLocals = {
  user: { id: string; name: string; avatar?: string };
  posts: Array<{ title: string; content: string; createdAt: Date }>;
};

export function renderTemplate(res: Response, view: string, locals: TemplateLocals) {
  res.render(view, locals);
}

调用这个函数时，TypeScript会自动校验locals的类型是否符合定义，避免传递错误数据。

5. 模板内语法与类型提示 #

虽然TS无法直接检查EJS模板内的<%%>代码，但可以通过以下方式提升体验：

• 用ejs-lint检查模板语法：在package.json中添加脚本"lint:ejs": "ejs-lint src/views/**/*.ejs"，运行npm run lint:ejs即可检查语法错误。
• 在模板中使用类型注释（可选）：比如<% // @type {typeof locals.user} const user = locals.user %>，部分编辑器（如VS Code）会提供基础的类型提示。

内容的提问来源于stack exchange，提问作者adeelch