在Express Handler函数中使用Async/Await触发TypeScript ESLint错误

你的代码如下：

import { Handler } from 'express'

export const fooHandler: Handler = async (_req, res) => {
  await new Promise(resolve => setTimeout(resolve, 1000));
  res.send('');
};

触发的ESLint错误为：

Promise-returning function provided to variable where a void return was expected (eslint@typescript-eslint/no-misused-promises)

关于规则的说明 #

@typescript-eslint/no-misused-promises并非新增规则，但它的检测逻辑在后续版本中有所更新，尤其是对返回void类型的函数是否返回Promise的校验更严格了。

Express的Handler类型默认定义返回值为void，但异步函数本质上会返回Promise<void>，这就造成了类型不匹配。旧项目能正常运行，大概率是因为：

• 旧项目使用的@typescript-eslint/eslint-plugin版本较低，当时该规则未对这种场景做严格检测；
• 旧项目没有启用这个ESLint规则。

解决办法 #

有两种常见的处理方式：

1. 明确指定返回类型
   给异步函数标注返回类型为Promise<void>，让类型定义和实际返回值匹配：

   import { Handler } from 'express'
   
   export const fooHandler: Handler = async (_req, res): Promise<void> => {
     await new Promise(resolve => setTimeout(resolve, 1000));
     res.send('');
   };
   

2. 调整ESLint规则配置
   如果不想修改代码，可以在ESLint配置文件中放宽该规则对void返回值的检测：

   module.exports = {
     // 其他配置项...
     rules: {
       '@typescript-eslint/no-misused-promises': [
         'error',
         {
           checksVoidReturn: false
         }
       ]
     }
   };
   

   或者更精准地针对Express Handler场景配置，避免全局放宽：

   module.exports = {
     // 其他配置项...
     overrides: [
       {
         files: ['*.ts'],
         rules: {
           '@typescript-eslint/no-misused-promises': [
             'error',
             {
               checksVoidReturn: {
                 attributes: false
               }
             }
           ]
         }
       }
     ]
   };
   

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