如何为Express.js特定端点设置完整请求接收超时？

Express v4.17, Node v18

问题描述： #

我有一个/upload端点，希望客户端能在单个请求中持续数小时上传数据。

但Node的server.requestTimeout默认值为5分钟，会超时任何运行超过该时长的请求，这对大文件上传来说不够。我不想全局提高requestTimeout的值。

在req对象上设置超时并非我所需：

• req.setTimeout(ms)是req.socket.setTimeout(ms)的别名
• req.socket.setTimeout(ms)设置的是SOCKET超时

  Socket超时是等待单个数据包的超时时间，常见误解是将其视为接收完整响应的超时。

• req.connection.setTimeout(ms)设置的是连接建立的最长时间

  连接超时是程序等待与另一个进程建立连接的最长时间，此时还未收发任何应用数据，仅建立连接本身。

已尝试方案： #

我尝试直接在req对象（以及res对象，曾看到有人建议这么做）上设置超时：

以下是示例中间件函数：

const reqTimeoutSetter = (req, res, next) => {
    req.setTimeout(3600000); // one hour
    req.socket.setTimeout(3600000);
    req.connection.setTimeout(3600000);

    res.setTimeout(3600000);
    res.socket.setTimeout(3600000);
    res.connection.setTimeout(3600000);

    next();
};

我的端点及服务器配置如下：

const app = express();

app.post('/', [reqTimeoutSetter, /* multer middleware */], (req, res) => {
    // ...
});

const server = http.createServer({
    requestTimeout: 10000 // 10 seconds
}, app);

server.listen(5000);

但请求仍会根据server.requestTimeout的值超时。

是否有办法为特定端点（而非全局）设置接收客户端完整请求的超时时间？

解决方案 #

可以通过两种方式实现特定端点的请求超时自定义，核心是干预Node.js的requestTimeout定时器逻辑：

方法1：在端点中间件中重置超时定时器 #

Node.js会为每个请求绑定全局requestTimeout对应的定时器，我们可以在目标端点的前置中间件中清除该定时器，并为当前请求设置新的超时时间：

const reqTimeoutSetter = (req, res, next) => {
    // 清除全局设置的requestTimeout定时器
    if (req.timeout) {
        clearTimeout(req.timeout);
    }
    // 为当前上传请求设置1小时超时
    req.timeout = setTimeout(() => {
        req.destroy(new Error('Upload request timed out'));
    }, 3600000);
    
    // 请求结束后清理定时器，避免内存泄漏
    const cleanup = () => {
        clearTimeout(req.timeout);
        res.off('finish', cleanup);
        res.off('close', cleanup);
        req.off('end', cleanup);
        req.off('abort', cleanup);
    };
    res.on('finish', cleanup);
    res.on('close', cleanup);
    req.on('end', cleanup);
    req.on('abort', cleanup);

    next();
};

// 注意：该中间件要放在multer等上传处理中间件之前
app.post('/upload', [reqTimeoutSetter, /* multer middleware */], (req, res) => {
    // 处理上传逻辑
});

方法2：通过服务器timeout事件动态判断 #

利用服务器的timeout事件，根据请求路径和方法判断是否延长超时时间：

const server = http.createServer({
    requestTimeout: 10000 // 全局默认10秒超时
}, app);

server.on('timeout', (req) => {
    // 仅对/upload的POST请求延长超时
    if (req.url === '/upload' && req.method === 'POST') {
        req.setTimeout(3600000, () => {
            req.destroy(new Error('Upload timed out after 1 hour'));
        });
    } else {
        // 其他请求按全局规则终止
        req.destroy(new Error('Request timed out'));
    }
});

server.listen(5000);

关键注意事项 #

• 如果使用multer等文件上传中间件，超时设置逻辑必须在上传中间件之前执行，确保在文件传输开始前就重置超时规则。
• 无论哪种方法，都要在请求完成（成功、失败、中断）时清理定时器，防止内存泄漏。

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