线上 Node.js 服务每隔几天就会在日志里抛出一个 `EPIPE` 错误，进程不崩溃，但请求链路会留下 500。这个错误通常出现在向一个已经关闭的 socket 写数据时，比如客户端提前断开、反向代理超时关闭连接，或者子进程的 stdin 被关闭后父进程还在写入。Node.js 的 `net.Socket` 和 `stream.Writable` 在管道断裂时会触发 `error` 事件，如果没人监听，默认行为就是抛异常。很多人第一次看到堆栈里只有 `write` 和 `afterWriteDispatched`，误以为是业务代码问题，其实根因在连接生命周期管理。下面从一次实际排查过程出发，说明如何定位 EPIPE 的来源，以及在 HTTP 服务、子进程通信和日志写入这三类场景里怎样避免它变成未捕获异常。

一次典型的日志长这样：

```
Error: write EPIPE
 at afterWriteDispatched (node:internal/stream_base_commons:166:9)
 at writeGeneric (node:internal/stream_base_commons:137:15)
 at Socket._writeGeneric (node:net:776:11)
 at Socket._write (node:net:788:21)
 at writeOrBuffer (node:internal/streams/writable:392:12)
 at Socket.write (node:internal/streams/writable:334:20)
 at /app/src/logger.js:42:18
```

堆栈指向我们自己的日志模块，但日志模块只是往一个 `net.Socket` 写数据。这个 socket 来自一个 sidecar 日志收集进程，它崩溃重启时旧连接会变成半开状态。父进程继续 `write`，第一次可能成功，第二次就拿到 EPIPE。

先确认错误来源。在 Node.js 里，`process.on('uncaughtException')` 能兜住它，但这不是修复，只是让进程别退出。更靠谱的做法是给所有可能断裂的流挂上 `error` 监听，并区分错误类型。

```js
const net = require('net');

const socket = net.connect(9000, '127.0.0.1');

socket.on('error', (err) => {
 if (err.code === 'EPIPE') {
 console.warn('log sidecar connection closed, dropping current batch');
 // 触发重连逻辑，不要在这里直接退出
 scheduleReconnect();
 } else {
 console.error('unexpected socket error', err);
 }
});
```

对于 HTTP 服务，EPIPE 更常见的来源是客户端在响应写完之前断开。例如一个慢接口返回大 JSON，浏览器标签被关掉，Node 的 `res.write()` 就会遇到 EPIPE。Express 默认不会把这个错误冒泡到路由，但底层 `http.ServerResponse` 是流，需要单独处理。

```js
app.use((req, res, next) => {
 res.on('error', (err) => {
 if (err.code === 'EPIPE') return;
 next(err);
 });
 next();
});
```

如果是用 `child_process.spawn` 做任务处理，父进程往子进程 stdin 写任务时，子进程可能因为内存超限被 kill，stdin 随之关闭。这时 `child.stdin.write()` 会触发 EPIPE。一个实用做法是在每次写入前检查 `child.stdin.writable`，并在 `child.on('exit')` 里把 stdin 引用置空。

```js
function sendTask(child, payload) {
 if (!child.stdin || !child.stdin.writable) {
 throw new Error('worker stdin is not writable');
 }
 child.stdin.write(JSON.stringify(payload) + '\n');
}

child.on('exit', () => {
 pendingTasks.forEach((task) => task.reject(new Error('worker exited')));
 pendingTasks.length = 0;
});
```

日志写入场景里还有一个容易忽略的点：用 `fs.createWriteStream` 写文件时，磁盘满或者路径所在卷被卸载，也会出现 EPIPE 或 ENOSPC。写流需要监听 `error`，并且在 `error` 之后重建流，否则后续写入全部失败。

```js
function createLogStream(path) {
 const stream = fs.createWriteStream(path, { flags: 'a' });
 stream.on('error', (err) => {
 console.error('log stream error', err.code);
 // 标记当前流不可用，由外部定时器重建
 });
 return stream;
}
```

真正要减少 EPIPE 的出现，重点不是捕获它，而是让写入方知道连接已经不可用。TCP 的半开连接检测依赖 keepalive，Node 默认不开启。对于长连接场景，在 socket 上设置 `socket.setKeepAlive(true, 30000)` 可以让内核更早发现对端消失，减少往死连接里写数据的窗口。

```js
socket.setKeepAlive(true, 30000);
socket.setTimeout(60000, () => {
 socket.destroy();
});
```

另一个实践是在应用层做写入节流和失败重试。向外部进程或远端写日志时，维护一个小的内存队列，写入失败时把当前批次放回队列头部，等待重连成功后再 flush。这样即使 sidecar 短暂重启，也不会丢日志，更不会让 EPIPE 冒到主流程。

```js
class BufferedWriter {
 constructor(connect) {
 this.queue = [];
 this.socket = null;
 this.connect = connect;
 }

 write(chunk) {
 this.queue.push(chunk);
 this.flush();
 }

 flush() {
 if (!this.socket || !this.socket.writable) return;
 while (this.queue.length) {
 const chunk = this.queue.shift();
 const ok = this.socket.write(chunk);
 if (!ok) {
 this.socket.once('drain', () => this.flush());
 break;
 }
 }
 }

 reconnect() {
 this.socket = this.connect();
 this.socket.on('error', () => {
 this.socket = null;
 setTimeout(() => this.reconnect(), 1000);
 });
 this.socket.on('connect', () => this.flush());
 }
}
```

在排查时，给每个 socket 和流加上标识，比如 `socket._tag = 'log-sidecar'`，然后在错误日志里带上这个 tag，能很快区分是哪个连接出的问题。不要依赖堆栈里的文件名，流错误的堆栈经常只指向 Node 内部模块。

最后提一个 Node 版本相关的细节。在 Node 18 之后，`stream.write` 在错误后如果没有回调，错误会以 `error` 事件形式发出；如果传了回调，回调会收到错误。混用两种风格容易漏掉错误。统一用回调或者统一监听 `error`，选一种并在代码库中保持一致，排查成本会低很多。

 推荐查看：https:://www.52cha.cn/hanzi/9996.html
 推荐查看：https:://www.52cha.cn/hanzi/9997.html
 推荐查看：https:://www.52cha.cn/hanzi/9998.html
 推荐查看：https:://www.52cha.cn/hanzi/9999.html
 推荐查看：https:://www.52cha.cn/hanzi/10000.html
 推荐查看：https:://www.52cha.cn/hanzi/10001.html
 推荐查看：https:://www.52cha.cn/hanzi/10002.html
 推荐查看：https:://www.52cha.cn/hanzi/10003.html
 推荐查看：https:://www.52cha.cn/hanzi/10004.html
 推荐查看：https:://www.52cha.cn/hanzi/10005.html
 推荐查看：https:://www.52cha.cn/hanzi/10006.html
 推荐查看：https:://www.52cha.cn/hanzi/10007.html
 推荐查看：https:://www.52cha.cn/hanzi/10008.html
 推荐查看：https:://www.52cha.cn/hanzi/10009.html
 推荐查看：https:://www.52cha.cn/hanzi/10010.html
 推荐查看：https:://www.52cha.cn/hanzi/10011.html
 推荐查看：https:://www.52cha.cn/hanzi/10012.html
 推荐查看：https:://www.52cha.cn/hanzi/10013.html
 推荐查看：https:://www.52cha.cn/hanzi/10014.html
 推荐查看：https:://www.52cha.cn/hanzi/10015.html
 推荐查看：https:://www.52cha.cn/hanzi/10016.html
 推荐查看：https:://www.52cha.cn/hanzi/10017.html
 推荐查看：https:://www.52cha.cn/hanzi/10018.html
 推荐查看：https:://www.52cha.cn/hanzi/10019.html
 推荐查看：https:://www.52cha.cn/hanzi/10020.html
 推荐查看：https:://www.52cha.cn/hanzi/10021.html
 推荐查看：https:://www.52cha.cn/hanzi/10022.html
 推荐查看：https:://www.52cha.cn/hanzi/10023.html
 推荐查看：https:://www.52cha.cn/hanzi/10024.html
 推荐查看：https:://www.52cha.cn/hanzi/10025.html
 推荐查看：https:://www.52cha.cn/hanzi/10026.html
 推荐查看：https:://www.52cha.cn/hanzi/10027.html
 推荐查看：https:://www.52cha.cn/hanzi/10028.html
 推荐查看：https:://www.52cha.cn/hanzi/10029.html
 推荐查看：https:://www.52cha.cn/hanzi/10030.html
 推荐查看：https:://www.52cha.cn/hanzi/10031.html
 推荐查看：https:://www.52cha.cn/hanzi/10032.html
 推荐查看：https:://www.52cha.cn/hanzi/10033.html
 推荐查看：https:://www.52cha.cn/hanzi/10034.html
 推荐查看：https:://www.52cha.cn/hanzi/10035.html
 推荐查看：https:://www.52cha.cn/hanzi/10036.html
 推荐查看：https:://www.52cha.cn/hanzi/10037.html
 推荐查看：https:://www.52cha.cn/hanzi/10038.html
 推荐查看：https:://www.52cha.cn/hanzi/10039.html
 推荐查看：https:://www.52cha.cn/hanzi/10040.html
 推荐查看：https:://www.52cha.cn/hanzi/10041.html
 推荐查看：https:://www.52cha.cn/hanzi/10042.html
 推荐查看：https:://www.52cha.cn/hanzi/10043.html
 推荐查看：https:://www.52cha.cn/hanzi/10044.html
 推荐查看：https:://www.52cha.cn/hanzi/10045.html
 推荐查看：https:://www.52cha.cn/hanzi/10046.html
 推荐查看：https:://www.52cha.cn/hanzi/10047.html
 推荐查看：https:://www.52cha.cn/hanzi/10048.html
 推荐查看：https:://www.52cha.cn/hanzi/10049.html
 推荐查看：https:://www.52cha.cn/hanzi/10050.html
 推荐查看：https:://www.52cha.cn/hanzi/10051.html
 推荐查看：https:://www.52cha.cn/hanzi/10052.html
 推荐查看：https:://www.52cha.cn/hanzi/10053.html
 推荐查看：https:://www.52cha.cn/hanzi/10054.html
 推荐查看：https:://www.52cha.cn/hanzi/10055.html
 推荐查看：https:://www.52cha.cn/hanzi/10056.html
 推荐查看：https:://www.52cha.cn/hanzi/10057.html
 推荐查看：https:://www.52cha.cn/hanzi/10058.html
 推荐查看：https:://www.52cha.cn/hanzi/10059.html
 推荐查看：https:://www.52cha.cn/hanzi/10060.html
 推荐查看：https:://www.52cha.cn/hanzi/10061.html
 推荐查看：https:://www.52cha.cn/hanzi/10062.html
 推荐查看：https:://www.52cha.cn/hanzi/10063.html
 推荐查看：https:://www.52cha.cn/hanzi/10064.html
 推荐查看：https:://www.52cha.cn/hanzi/10065.html
 推荐查看：https:://www.52cha.cn/hanzi/10066.html
 推荐查看：https:://www.52cha.cn/hanzi/10067.html
 推荐查看：https:://www.52cha.cn/hanzi/10068.html
 推荐查看：https:://www.52cha.cn/hanzi/10069.html
 推荐查看：https:://www.52cha.cn/hanzi/10070.html
 推荐查看：https:://www.52cha.cn/hanzi/10071.html
 推荐查看：https:://www.52cha.cn/hanzi/10072.html
 推荐查看：https:://www.52cha.cn/hanzi/10073.html
 推荐查看：https:://www.52cha.cn/hanzi/10074.html
 推荐查看：https:://www.52cha.cn/hanzi/10075.html
 推荐查看：https:://www.52cha.cn/hanzi/10076.html
 推荐查看：https:://www.52cha.cn/hanzi/10077.html
 推荐查看：https:://www.52cha.cn/hanzi/10078.html
 推荐查看：https:://www.52cha.cn/hanzi/10079.html
 推荐查看：https:://www.52cha.cn/hanzi/10080.html
 推荐查看：https:://www.52cha.cn/hanzi/10081.html
 推荐查看：https:://www.52cha.cn/hanzi/10082.html
 推荐查看：https:://www.52cha.cn/hanzi/10083.html
 推荐查看：https:://www.52cha.cn/hanzi/10084.html
 推荐查看：https:://www.52cha.cn/hanzi/10085.html
 推荐查看：https:://www.52cha.cn/hanzi/10086.html
 推荐查看：https:://www.52cha.cn/hanzi/10087.html
 推荐查看：https:://www.52cha.cn/hanzi/10088.html
 推荐查看：https:://www.52cha.cn/hanzi/10089.html
 推荐查看：https:://www.52cha.cn/hanzi/10090.html
 推荐查看：https:://www.52cha.cn/hanzi/10091.html
 推荐查看：https:://www.52cha.cn/hanzi/10092.html
 推荐查看：https:://www.52cha.cn/hanzi/10093.html
 推荐查看：https:://www.52cha.cn/hanzi/10094.html
 推荐查看：https:://www.52cha.cn/hanzi/10095.html
 推荐查看：https:://www.52cha.cn/hanzi/10096.html
 推荐查看：https:://www.52cha.cn/hanzi/10097.html
 推荐查看：https:://www.52cha.cn/hanzi/10098.html
 推荐查看：https:://www.52cha.cn/hanzi/10099.html
 推荐查看：https:://www.52cha.cn/hanzi/10100.html
 推荐查看：https:://www.52cha.cn/hanzi/10101.html
 推荐查看：https:://www.52cha.cn/hanzi/10102.html
 推荐查看：https:://www.52cha.cn/hanzi/10103.html
 推荐查看：https:://www.52cha.cn/hanzi/10104.html
 推荐查看：https:://www.52cha.cn/hanzi/10105.html
 推荐查看：https:://www.52cha.cn/hanzi/10106.html
 推荐查看：https:://www.52cha.cn/hanzi/10107.html
 推荐查看：https:://www.52cha.cn/hanzi/10108.html
 推荐查看：https:://www.52cha.cn/hanzi/10109.html
 推荐查看：https:://www.52cha.cn/hanzi/10110.html
 推荐查看：https:://www.52cha.cn/hanzi/10111.html
 推荐查看：https:://www.52cha.cn/hanzi/10112.html
 推荐查看：https:://www.52cha.cn/hanzi/10113.html
 推荐查看：https:://www.52cha.cn/hanzi/10114.html
 推荐查看：https:://www.52cha.cn/hanzi/10115.html
 推荐查看：https:://www.52cha.cn/hanzi/10116.html
 推荐查看：https:://www.52cha.cn/hanzi/10117.html
 推荐查看：https:://www.52cha.cn/hanzi/10118.html
 推荐查看：https:://www.52cha.cn/hanzi/10119.html
 推荐查看：https:://www.52cha.cn/hanzi/10120.html
 推荐查看：https:://www.52cha.cn/hanzi/10121.html
 推荐查看：https:://www.52cha.cn/hanzi/10122.html
 推荐查看：https:://www.52cha.cn/hanzi/10123.html
 推荐查看：https:://www.52cha.cn/hanzi/10124.html
 推荐查看：https:://www.52cha.cn/hanzi/10125.html
 推荐查看：https:://www.52cha.cn/hanzi/10126.html
 推荐查看：https:://www.52cha.cn/hanzi/10127.html
 推荐查看：https:://www.52cha.cn/hanzi/10128.html
 推荐查看：https:://www.52cha.cn/hanzi/10129.html
 推荐查看：https:://www.52cha.cn/hanzi/10130.html
 推荐查看：https:://www.52cha.cn/hanzi/10131.html
 推荐查看：https:://www.52cha.cn/hanzi/10132.html
 推荐查看：https:://www.52cha.cn/hanzi/10133.html
 推荐查看：https:://www.52cha.cn/hanzi/10134.html
 推荐查看：https:://www.52cha.cn/hanzi/10135.html
 推荐查看：https:://www.52cha.cn/hanzi/10136.html
 推荐查看：https:://www.52cha.cn/hanzi/10137.html
 推荐查看：https:://www.52cha.cn/hanzi/10138.html
 推荐查看：https:://www.52cha.cn/hanzi/10139.html
 推荐查看：https:://www.52cha.cn/hanzi/10140.html
 推荐查看：https:://www.52cha.cn/hanzi/10141.html
 推荐查看：https:://www.52cha.cn/hanzi/10142.html
 推荐查看：https:://www.52cha.cn/hanzi/10143.html
 推荐查看：https:://www.52cha.cn/hanzi/10144.html
 推荐查看：https:://www.52cha.cn/hanzi/10145.html
 推荐查看：https:://www.52cha.cn/hanzi/10146.html
 推荐查看：https:://www.52cha.cn/hanzi/10147.html
 推荐查看：https:://www.52cha.cn/hanzi/10148.html
 推荐查看：https:://www.52cha.cn/hanzi/10149.html
 推荐查看：https:://www.52cha.cn/hanzi/10150.html
 推荐查看：https:://www.52cha.cn/hanzi/10151.html
 推荐查看：https:://www.52cha.cn/hanzi/10152.html
 推荐查看：https:://www.52cha.cn/hanzi/10153.html
 推荐查看：https:://www.52cha.cn/hanzi/10154.html
 推荐查看：https:://www.52cha.cn/hanzi/10155.html
 推荐查看：https:://www.52cha.cn/hanzi/10156.html
 推荐查看：https:://www.52cha.cn/hanzi/10157.html
 推荐查看：https:://www.52cha.cn/hanzi/10158.html
 推荐查看：https:://www.52cha.cn/hanzi/10159.html
 推荐查看：https:://www.52cha.cn/hanzi/10160.html
 推荐查看：https:://www.52cha.cn/hanzi/10161.html
 推荐查看：https:://www.52cha.cn/hanzi/10162.html
 推荐查看：https:://www.52cha.cn/hanzi/10163.html
 推荐查看：https:://www.52cha.cn/hanzi/10164.html
 推荐查看：https:://www.52cha.cn/hanzi/10165.html
 推荐查看：https:://www.52cha.cn/hanzi/10166.html
 推荐查看：https:://www.52cha.cn/hanzi/10167.html
 推荐查看：https:://www.52cha.cn/hanzi/10168.html
 推荐查看：https:://www.52cha.cn/hanzi/10169.html
 推荐查看：https:://www.52cha.cn/hanzi/10170.html
 推荐查看：https:://www.52cha.cn/hanzi/10171.html
 推荐查看：https:://www.52cha.cn/hanzi/10172.html
 推荐查看：https:://www.52cha.cn/hanzi/10173.html
 推荐查看：https:://www.52cha.cn/hanzi/10174.html
 推荐查看：https:://www.52cha.cn/hanzi/10175.html
 推荐查看：https:://www.52cha.cn/hanzi/10176.html
 推荐查看：https:://www.52cha.cn/hanzi/10177.html
 推荐查看：https:://www.52cha.cn/hanzi/10178.html
 推荐查看：https:://www.52cha.cn/hanzi/10179.html
 推荐查看：https:://www.52cha.cn/hanzi/10180.html
 推荐查看：https:://www.52cha.cn/hanzi/10181.html
 推荐查看：https:://www.52cha.cn/hanzi/10182.html
 推荐查看：https:://www.52cha.cn/hanzi/10183.html
 推荐查看：https:://www.52cha.cn/hanzi/10184.html
 推荐查看：https:://www.52cha.cn/hanzi/10185.html
 推荐查看：https:://www.52cha.cn/hanzi/10186.html
 推荐查看：https:://www.52cha.cn/hanzi/10187.html
 推荐查看：https:://www.52cha.cn/hanzi/10188.html
 推荐查看：https:://www.52cha.cn/hanzi/10189.html
 推荐查看：https:://www.52cha.cn/hanzi/10190.html
 推荐查看：https:://www.52cha.cn/hanzi/10191.html
 推荐查看：https:://www.52cha.cn/hanzi/10192.html
 推荐查看：https:://www.52cha.cn/hanzi/10193.html
 推荐查看：https:://www.52cha.cn/hanzi/10194.html
 推荐查看：https:://www.52cha.cn/hanzi/10195.html

线上 Node.js 服务每隔几天就会在日志里抛出一个 EPIPE 错误，进程不崩溃，但请求链路会留下 500。这个错误通常出现在向一个已经关闭的 socket 写数据时，比如客户端提前断开、反向代理超时关闭连接，或者子进程的 stdin 被关闭后父进程还在写入。Node.js 的 net.Socket 和 stream.Writable 在管道断裂时会触发 error 事件，如果没人监听，默认行为就是抛异常。很多人第一次看到堆栈里只有 write 和 afterWriteDispatched，误以为是业务代码问题，其实根因在连接生命周期管理。下面从一次实际排查过程出发，说明如何定位 EPIPE 的来源，以及在 HTTP 服务、子进程通信和日志写入这三类场景里怎样避免它变成未捕获异常。

Node.js 中遇到 EPIPE 错误：从日志排查到代码修复

线上 Node.js 服务每隔几天就会在日志里抛出一个 EPIPE 错误，进程不崩溃，但请求链路会留下 500。这个错误通常出现在向一个已经关闭的 socket 写数据时，比如客户端提前断开、反向代理超时关闭连接，或者子进程的 stdin 被关闭后父进程还在写入。Node.js 的 net.Socket 和 stream.Writable 在管道断裂时会触发 error 事件，如果没人监听，默认行

编程语言

Node.js服务频繁出现EPIPE错误导致500，根因是向已关闭socket写入数据，常见于客户端断开、代理超时或子进程退出。提供错误监听、连接状态检查、keepalive配置、缓冲队列及统一错误处理等实用策略，有效避免未捕获异常，保障服务稳定。

代码解释

路由

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Node.js 中遇到 EPIPE 错误：从日志排查到代码修复-腾讯云开发者社区-腾讯云

Node.js 中遇到 EPIPE 错误：从日志排查到代码修复

Node.js 中遇到 EPIPE 错误：从日志排查到代码修复

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐