在 Node.js 里做定时任务或者 CLI 工具时，用 `fs.writeFile` 落盘一个 JSON 状态文件是很常见的操作，比如记录上次同步时间、缓存上一次运行的结果、写一个简单的持久化配置。单进程、单次调用时它工作得很好，可一旦同一个文件被多个异步流程同时写，问题就冒出来了：文件内容时不时变成两条 JSON 拼在一起的残缺字符串，或者干脆变成 0 字节。更让人抓狂的是，这种问题往往在本地跑几百次都复现不了，上了生产环境、并发一高就开始丢数据。`fs.writeFile` 本身并没有 bug，它只是「打开文件、写入、关闭」这个语义不带任何互斥或事务保证，多个调用交错执行时，后打开的 fd 会截断先写入的内容。这篇文章从一次实际遇到的空文件问题出发，拆解 `writeFile` 的底层行为，给出用内存队列串行化写入、用临时文件加 `rename` 做原子替换、以及处理进程级并发和异常中断的落地做法，顺带聊聊 `fs.promises` 和 `FileHandle` 在细节上的差别。

先看一段从真实项目里抽出来的代码，它负责把运行状态写进一个 JSON 文件：

```js
const fs = require('fs/promises')

async function saveState(state) {
 const raw = JSON.stringify(state, null, 2)
 await fs.writeFile('./state.json', raw, 'utf8')
}

// 两个异步任务几乎同时触发
saveState({ cursor: 100 })
saveState({ cursor: 200 })
```

直觉上后一次调用会覆盖前一次，结果应该是 `{ cursor: 200 }`。但实际跑起来偶尔会读到 `{"cursor":100}{"cursor":200}` 这种非法 JSON，或者 `{ cursor: 200 }` 后面跟着半截 `100` 的残渣。原因藏在 `fs.writeFile` 的实现里：它在内部先以 `'w'` 标志打开文件，`O_TRUNC` 会把文件长度截断成 0，然后从 offset 0 开始写。两个调用都完成了 open 之后，fd 的偏移各自独立，写入顺序完全由事件循环调度决定。如果 A 的 truncate 发生在 B 写完之后，B 的内容就没了；如果两个 write 交错提交，就会得到拼接的脏数据。它压根不是原子的。

要避免交错，最直接的办法是让所有写入排进一个串行队列。用一个 promise 链把写操作串起来，前一个没结束前一个不开始：

```js
let writeQueue = Promise.resolve()

function enqueueWrite(task) {
 const next = writeQueue.then(task, task)
 // 吞掉错误避免队列断链，错误仍由调用方 catch
 writeQueue = next.catch(() => {})
 return next
}

function saveState(state) {
 return enqueueWrite(async () => {
 const raw = JSON.stringify(state, null, 2)
 await fs.writeFile('./state.json', raw, 'utf8')
 })
}
```

这样同一进程内的并发调用会被强制排队，写入顺序确定，不会再发生截断竞争。注意 `then(task, task)` 这个写法，是为了让前一个任务失败时队列不断掉，否则后续写入永远挂起。

串行化解决了「交错」，但没解决「写到一半进程被杀」。`writeFile` 在写大文件时并不是一次 `write` 系统调用完成的，中间如果进程崩溃、机器断电，文件就停在半截状态。对配置文件来说，宁可保留旧版本，也不能留一个坏文件。做法是写临时文件再 `rename` 过去：

```js
const path = require('path')
const crypto = require('crypto')

async function atomicWrite(file, raw) {
 const dir = path.dirname(file)
 const tmp = path.join(dir, `.${path.basename(file)}.${crypto.randomBytes(6).toString('hex')}.tmp`)
 const handle = await fs.open(tmp, 'w')
 try {
 await handle.writeFile(raw, 'utf8')
 await handle.sync() // 确保数据真正落到磁盘，再 rename
 } finally {
 await handle.close()
 }
 await fs.rename(tmp, file)
}
```

`rename` 在同一文件系统内是原子操作，目标文件要么是旧的完整内容，要么是新的完整内容，不会出现中间态。`handle.sync()` 这一步容易被省掉，但在对持久性有要求的场景（比如断电后要能恢复）不能少，它保证数据已经从页缓存刷到存储设备，否则 rename 先落盘、数据后落盘，依然可能拿到空文件。另外临时文件名带上随机后缀，避免两个进程同时写时争抢同一个临时文件。

进程内的队列管不到多进程。如果你的 Node 服务用 `cluster` 或者 PM2 开了多实例，同时操作同一个状态文件，队列就失效了。这种情况要么用文件锁，比如 `proper-lockfile`，在写之前对目标路径加独占锁；要么干脆换掉存储介质，改用 SQLite、Redis 这类自带并发控制的方案。状态文件这种小数据量场景，用 `proper-lockfile` 是侵入性最小的选择：

```js
const lockfile = require('proper-lockfile')

async function saveStateLocked(file, state) {
 const release = await lockfile.lock(file, { retries: { retries: 5, minTimeout: 50 } })
 try {
 await atomicWrite(file, JSON.stringify(state, null, 2))
 } finally {
 await release()
 }
}
```

还有一点值得留意：`fs.writeFile` 和 `fs.promises.writeFile` 在 Node 版本较老时对 `AbortSignal` 的支持不完整，写了 `signal` 也未必能中断正在进行的系统调用。如果写入可能很大又想能取消，用 `FileHandle.createWriteStream` 自己控制流更稳。

把这些拼起来，一个能扛住并发、崩溃和多进程的状态写入大致长这样：先加文件锁，再串行进入写临时文件、`sync`、`rename`、释放锁。听起来步骤不少，但每一层对应一个具体的失败模式：锁管跨进程，队列管跨异步调用，临时文件管写到一半，`sync` 管断电顺序。搞清楚 `writeFile` 不提供什么，比记住它提供什么更有用。

 推荐查看组词：https://www.ttctq.com/zuci/11443.html
 推荐查看组词：https://www.ttctq.com/zuci/11444.html
 推荐查看组词：https://www.ttctq.com/zuci/11445.html
 推荐查看组词：https://www.ttctq.com/zuci/11446.html
 推荐查看组词：https://www.ttctq.com/zuci/11447.html
 推荐查看组词：https://www.ttctq.com/zuci/11448.html
 推荐查看组词：https://www.ttctq.com/zuci/11449.html
 推荐查看组词：https://www.ttctq.com/zuci/11450.html
 推荐查看组词：https://www.ttctq.com/zuci/11451.html
 推荐查看组词：https://www.ttctq.com/zuci/11452.html
 推荐查看组词：https://www.ttctq.com/zuci/11453.html
 推荐查看组词：https://www.ttctq.com/zuci/11454.html
 推荐查看组词：https://www.ttctq.com/zuci/11455.html
 推荐查看组词：https://www.ttctq.com/zuci/11456.html
 推荐查看组词：https://www.ttctq.com/zuci/11457.html
 推荐查看组词：https://www.ttctq.com/zuci/11458.html
 推荐查看组词：https://www.ttctq.com/zuci/11459.html
 推荐查看组词：https://www.ttctq.com/zuci/11460.html
 推荐查看组词：https://www.ttctq.com/zuci/11461.html
 推荐查看组词：https://www.ttctq.com/zuci/11462.html
 推荐查看组词：https://www.ttctq.com/zuci/11463.html
 推荐查看组词：https://www.ttctq.com/zuci/11464.html
 推荐查看组词：https://www.ttctq.com/zuci/11465.html
 推荐查看组词：https://www.ttctq.com/zuci/11466.html
 推荐查看组词：https://www.ttctq.com/zuci/11467.html
 推荐查看组词：https://www.ttctq.com/zuci/11468.html
 推荐查看组词：https://www.ttctq.com/zuci/11469.html
 推荐查看组词：https://www.ttctq.com/zuci/11470.html
 推荐查看组词：https://www.ttctq.com/zuci/11471.html
 推荐查看组词：https://www.ttctq.com/zuci/11472.html
 推荐查看组词：https://www.ttctq.com/zuci/11473.html
 推荐查看组词：https://www.ttctq.com/zuci/11474.html
 推荐查看组词：https://www.ttctq.com/zuci/11475.html
 推荐查看组词：https://www.ttctq.com/zuci/11476.html
 推荐查看组词：https://www.ttctq.com/zuci/11477.html
 推荐查看组词：https://www.ttctq.com/zuci/11478.html
 推荐查看组词：https://www.ttctq.com/zuci/11479.html
 推荐查看组词：https://www.ttctq.com/zuci/11480.html
 推荐查看组词：https://www.ttctq.com/zuci/11481.html
 推荐查看组词：https://www.ttctq.com/zuci/11482.html
 推荐查看组词：https://www.ttctq.com/zuci/11483.html
 推荐查看组词：https://www.ttctq.com/zuci/11484.html
 推荐查看组词：https://www.ttctq.com/zuci/11485.html
 推荐查看组词：https://www.ttctq.com/zuci/11486.html
 推荐查看组词：https://www.ttctq.com/zuci/11487.html
 推荐查看组词：https://www.ttctq.com/zuci/11488.html
 推荐查看组词：https://www.ttctq.com/zuci/11489.html
 推荐查看组词：https://www.ttctq.com/zuci/11490.html
 推荐查看组词：https://www.ttctq.com/zuci/11491.html
 推荐查看组词：https://www.ttctq.com/zuci/11492.html
 推荐查看组词：https://www.ttctq.com/zuci/11493.html
 推荐查看组词：https://www.ttctq.com/zuci/11494.html
 推荐查看组词：https://www.ttctq.com/zuci/11495.html
 推荐查看组词：https://www.ttctq.com/zuci/11496.html
 推荐查看组词：https://www.ttctq.com/zuci/11497.html
 推荐查看组词：https://www.ttctq.com/zuci/11498.html
 推荐查看组词：https://www.ttctq.com/zuci/11499.html
 推荐查看组词：https://www.ttctq.com/zuci/11500.html
 推荐查看组词：https://www.ttctq.com/zuci/11501.html
 推荐查看组词：https://www.ttctq.com/zuci/11502.html
 推荐查看组词：https://www.ttctq.com/zuci/11503.html
 推荐查看组词：https://www.ttctq.com/zuci/11504.html
 推荐查看组词：https://www.ttctq.com/zuci/11505.html
 推荐查看组词：https://www.ttctq.com/zuci/11506.html
 推荐查看组词：https://www.ttctq.com/zuci/11507.html
 推荐查看组词：https://www.ttctq.com/zuci/11508.html
 推荐查看组词：https://www.ttctq.com/zuci/11509.html
 推荐查看组词：https://www.ttctq.com/zuci/11510.html
 推荐查看组词：https://www.ttctq.com/zuci/11511.html
 推荐查看组词：https://www.ttctq.com/zuci/11512.html
 推荐查看组词：https://www.ttctq.com/zuci/11513.html
 推荐查看组词：https://www.ttctq.com/zuci/11514.html
 推荐查看组词：https://www.ttctq.com/zuci/11515.html
 推荐查看组词：https://www.ttctq.com/zuci/11516.html
 推荐查看组词：https://www.ttctq.com/zuci/11517.html
 推荐查看组词：https://www.ttctq.com/zuci/11518.html
 推荐查看组词：https://www.ttctq.com/zuci/11519.html
 推荐查看组词：https://www.ttctq.com/zuci/11520.html
 推荐查看组词：https://www.ttctq.com/zuci/11521.html
 推荐查看组词：https://www.ttctq.com/zuci/11522.html
 推荐查看组词：https://www.ttctq.com/zuci/11523.html
 推荐查看组词：https://www.ttctq.com/zuci/11524.html
 推荐查看组词：https://www.ttctq.com/zuci/11525.html
 推荐查看组词：https://www.ttctq.com/zuci/11526.html
 推荐查看组词：https://www.ttctq.com/zuci/11527.html
 推荐查看组词：https://www.ttctq.com/zuci/11528.html
 推荐查看组词：https://www.ttctq.com/zuci/11529.html
 推荐查看组词：https://www.ttctq.com/zuci/11530.html
 推荐查看组词：https://www.ttctq.com/zuci/11531.html
 推荐查看组词：https://www.ttctq.com/zuci/11532.html
 推荐查看组词：https://www.ttctq.com/zuci/11533.html
 推荐查看组词：https://www.ttctq.com/zuci/11534.html
 推荐查看组词：https://www.ttctq.com/zuci/11535.html
 推荐查看组词：https://www.ttctq.com/zuci/11536.html
 推荐查看组词：https://www.ttctq.com/zuci/11537.html
 推荐查看组词：https://www.ttctq.com/zuci/11538.html
 推荐查看组词：https://www.ttctq.com/zuci/11539.html
 推荐查看组词：https://www.ttctq.com/zuci/11540.html
 推荐查看组词：https://www.ttctq.com/zuci/11541.html
 推荐查看组词：https://www.ttctq.com/zuci/11542.html
 推荐查看组词：https://www.ttctq.com/zuci/11543.html
 推荐查看组词：https://www.ttctq.com/zuci/11544.html
 推荐查看组词：https://www.ttctq.com/zuci/11545.html
 推荐查看组词：https://www.ttctq.com/zuci/11546.html
 推荐查看组词：https://www.ttctq.com/zuci/11547.html
 推荐查看组词：https://www.ttctq.com/zuci/11548.html
 推荐查看组词：https://www.ttctq.com/zuci/11549.html
 推荐查看组词：https://www.ttctq.com/zuci/11550.html
 推荐查看组词：https://www.ttctq.com/zuci/11551.html
 推荐查看组词：https://www.ttctq.com/zuci/11552.html
 推荐查看组词：https://www.ttctq.com/zuci/11553.html
 推荐查看组词：https://www.ttctq.com/zuci/11554.html
 推荐查看组词：https://www.ttctq.com/zuci/11555.html
 推荐查看组词：https://www.ttctq.com/zuci/11556.html
 推荐查看组词：https://www.ttctq.com/zuci/11557.html
 推荐查看组词：https://www.ttctq.com/zuci/11558.html
 推荐查看组词：https://www.ttctq.com/zuci/11559.html
 推荐查看组词：https://www.ttctq.com/zuci/11560.html
 推荐查看组词：https://www.ttctq.com/zuci/11561.html
 推荐查看组词：https://www.ttctq.com/zuci/11562.html
 推荐查看组词：https://www.ttctq.com/zuci/11563.html
 推荐查看组词：https://www.ttctq.com/zuci/11564.html
 推荐查看组词：https://www.ttctq.com/zuci/11565.html
 推荐查看组词：https://www.ttctq.com/zuci/11566.html
 推荐查看组词：https://www.ttctq.com/zuci/11567.html
 推荐查看组词：https://www.ttctq.com/zuci/11568.html
 推荐查看组词：https://www.ttctq.com/zuci/11569.html
 推荐查看组词：https://www.ttctq.com/zuci/11570.html
 推荐查看组词：https://www.ttctq.com/zuci/11571.html
 推荐查看组词：https://www.ttctq.com/zuci/11572.html
 推荐查看组词：https://www.ttctq.com/zuci/11573.html
 推荐查看组词：https://www.ttctq.com/zuci/11574.html
 推荐查看组词：https://www.ttctq.com/zuci/11575.html
 推荐查看组词：https://www.ttctq.com/zuci/11576.html
 推荐查看组词：https://www.ttctq.com/zuci/11577.html
 推荐查看组词：https://www.ttctq.com/zuci/11578.html
 推荐查看组词：https://www.ttctq.com/zuci/11579.html
 推荐查看组词：https://www.ttctq.com/zuci/11580.html
 推荐查看组词：https://www.ttctq.com/zuci/11581.html
 推荐查看组词：https://www.ttctq.com/zuci/11582.html
 推荐查看组词：https://www.ttctq.com/zuci/11583.html
 推荐查看组词：https://www.ttctq.com/zuci/11584.html
 推荐查看组词：https://www.ttctq.com/zuci/11585.html
 推荐查看组词：https://www.ttctq.com/zuci/11586.html
 推荐查看组词：https://www.ttctq.com/zuci/11587.html
 推荐查看组词：https://www.ttctq.com/zuci/11588.html
 推荐查看组词：https://www.ttctq.com/zuci/11589.html
 推荐查看组词：https://www.ttctq.com/zuci/11590.html
 推荐查看组词：https://www.ttctq.com/zuci/11591.html
 推荐查看组词：https://www.ttctq.com/zuci/11592.html
 推荐查看组词：https://www.ttctq.com/zuci/11593.html
 推荐查看组词：https://www.ttctq.com/zuci/11594.html
 推荐查看组词：https://www.ttctq.com/zuci/11595.html
 推荐查看组词：https://www.ttctq.com/zuci/11596.html
 推荐查看组词：https://www.ttctq.com/zuci/11597.html
 推荐查看组词：https://www.ttctq.com/zuci/11598.html
 推荐查看组词：https://www.ttctq.com/zuci/11599.html
 推荐查看组词：https://www.ttctq.com/zuci/11600.html
 推荐查看组词：https://www.ttctq.com/zuci/11601.html
 推荐查看组词：https://www.ttctq.com/zuci/11602.html
 推荐查看组词：https://www.ttctq.com/zuci/11603.html
 推荐查看组词：https://www.ttctq.com/zuci/11604.html
 推荐查看组词：https://www.ttctq.com/zuci/11605.html
 推荐查看组词：https://www.ttctq.com/zuci/11606.html
 推荐查看组词：https://www.ttctq.com/zuci/11607.html
 推荐查看组词：https://www.ttctq.com/zuci/11608.html
 推荐查看组词：https://www.ttctq.com/zuci/11609.html
 推荐查看组词：https://www.ttctq.com/zuci/11610.html
 推荐查看组词：https://www.ttctq.com/zuci/11611.html
 推荐查看组词：https://www.ttctq.com/zuci/11612.html
 推荐查看组词：https://www.ttctq.com/zuci/11613.html
 推荐查看组词：https://www.ttctq.com/zuci/11614.html
 推荐查看组词：https://www.ttctq.com/zuci/11615.html
 推荐查看组词：https://www.ttctq.com/zuci/11616.html
 推荐查看组词：https://www.ttctq.com/zuci/11617.html
 推荐查看组词：https://www.ttctq.com/zuci/11618.html
 推荐查看组词：https://www.ttctq.com/zuci/11619.html
 推荐查看组词：https://www.ttctq.com/zuci/11620.html
 推荐查看组词：https://www.ttctq.com/zuci/11621.html
 推荐查看组词：https://www.ttctq.com/zuci/11622.html
 推荐查看组词：https://www.ttctq.com/zuci/11623.html
 推荐查看组词：https://www.ttctq.com/zuci/11624.html
 推荐查看组词：https://www.ttctq.com/zuci/11625.html
 推荐查看组词：https://www.ttctq.com/zuci/11626.html
 推荐查看组词：https://www.ttctq.com/zuci/11627.html
 推荐查看组词：https://www.ttctq.com/zuci/11628.html
 推荐查看组词：https://www.ttctq.com/zuci/11629.html
 推荐查看组词：https://www.ttctq.com/zuci/11630.html
 推荐查看组词：https://www.ttctq.com/zuci/11631.html
 推荐查看组词：https://www.ttctq.com/zuci/11632.html
 推荐查看组词：https://www.ttctq.com/zuci/11633.html
 推荐查看组词：https://www.ttctq.com/zuci/11634.html
 推荐查看组词：https://www.ttctq.com/zuci/11635.html
 推荐查看组词：https://www.ttctq.com/zuci/11636.html
 推荐查看组词：https://www.ttctq.com/zuci/11637.html
 推荐查看组词：https://www.ttctq.com/zuci/11638.html
 推荐查看组词：https://www.ttctq.com/zuci/11639.html
 推荐查看组词：https://www.ttctq.com/zuci/11640.html
 推荐查看组词：https://www.ttctq.com/zuci/11641.html
 推荐查看组词：https://www.ttctq.com/zuci/11642.html

在 Node.js 里做定时任务或者 CLI 工具时，用 fs.writeFile 落盘一个 JSON 状态文件是很常见的操作，比如记录上次同步时间、缓存上一次运行的结果、写一个简单的持久化配置。单进程、单次调用时它工作得很好，可一旦同一个文件被多个异步流程同时写，问题就冒出来了：文件内容时不时变成两条 JSON 拼在一起的残缺字符串，或者干脆变成 0 字节。更让人抓狂的是，这种问题往往在本地跑几百次都复现不了，上了生产环境、并发一高就开始丢数据。fs.writeFile 本身并没有 bug，它只是「打开文件、写入、关闭」这个语义不带任何互斥或事务保证，多个调用交错执行时，后打开的 fd 会截断先写入的内容。这篇文章从一次实际遇到的空文件问题出发，拆解 writeFile 的底层行为，给出用内存队列串行化写入、用临时文件加 rename 做原子替换、以及处理进程级并发和异常中断的落地做法，顺带聊聊 fs.promises 和 FileHandle 在细节上的差别。

Node.js 中 fs.writeFile 的并发写入陷阱：为什么你的 JSON 配置文件总被覆盖成空文件

在 Node.js 里做定时任务或者 CLI 工具时，用 fs.writeFile 落盘一个 JSON 状态文件是很常见的操作，比如记录上次同步时间、缓存上一次运行的结果、写一个简单的持久化配置。单进程、单次调用时它工作得很好，可一旦同一个文件被多个异步流程同时写，问题就冒出来了：文件内容时不时变成两条 JSON 拼在一起的残缺字符串，或者干脆变成 0 字节。更让人抓狂的是，这种问题往往在本地跑几

编程语言

后端

操作系统

Node.js中fs.writeFile并发写入JSON状态文件会导致数据截断或拼接损坏。解决策略包括：使用Promise链串行化写入操作、通过临时文件加rename实现原子替换、结合proper-lockfile处理多进程竞争，并利用handle.sync()确保数据落盘。构建稳定的持久化写入方案需同时考虑异步交错、进程崩溃及跨进程并发等场景。

文件系统

代码解释

SQLite

Redis

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

Node.js中fs.writeFile并发写入JSON状态文件会导致数据截断或拼接损坏。解决策略包括：使用Promise链串行化写入操作、通过临时文件加rename实现原子替换、结合proper-lockfile处理多进程竞争，并利用handle.sync()确保数据落盘。构建稳定的持久化写入方案需同时考虑异步交错、...

Node.js 中 fs.writeFile 的并发写入陷阱：为什么你的 JSON 配置文件总被覆盖成空文件-腾讯云开发者社区-腾讯云

Node.js 中 fs.writeFile 的并发写入陷阱：为什么你的 JSON 配置文件总被覆盖成空文件

Node.js 中 fs.writeFile 的并发写入陷阱：为什么你的 JSON 配置文件总被覆盖成空文件

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐