Node系列 · Node基础文件 I/ONode 的文件 I/O 几乎全靠fs模块。它同一份能力提供三套 API同步 / 异步回调 / Promise混用会产生事件循环被阻塞或回调金字塔问题。理解三者的取舍就能写好所有 Node 文件操作。一、fs 模块的三套 API同一个操作readFilefs提供三种写法风格函数返回阻塞主线程同步fs.readFileSync()数据 / 抛异常✅ 阻塞异步回调fs.readFile(cb)undefined / 通过 cb(err, data) 返回❌ 非阻塞Promisefs.promises.readFile()Promisedata / reject(err)❌ 非阻塞1.1 同步 APIconst fs require(node:fs); try { const data fs.readFileSync(./config.json, utf-8); console.log(JSON.parse(data)); } catch (err) { console.error(读取失败:, err.message); }1.2 异步回调 APIconst fs require(node:fs); fs.readFile(./config.json, utf-8, (err, data) { if (err) { console.error(读取失败:, err.message); return; } console.log(JSON.parse(data)); });回调第一个参数永远是err这是 Node 的错误优先回调约定。1.3 Promise API推荐const fs require(node:fs/promises); async function loadConfig() { try { const data await fs.readFile(./config.json, utf-8); return JSON.parse(data); } catch (err) { console.error(读取失败:, err.message); throw err; } } loadConfig().then((cfg) console.log(cfg));::: tip默认用 Promise 版本。它和 async/await 配合最自然错误用 try/catch 捕获与同步代码视觉上接近。同步版本只适合启动期必须串行的场景如读取配置文件初始化回调风格已基本被淘汰。:::二、读写文件2.1readFile完整签名// 异步 Promise 版 const buf await fs.readFile(path, options); // options 可以是 // string → utf-8 / hex / base64 / latin1 / ascii // object → { encoding, flag } // 省略 → 返回 Buffer不自动转字符串 const text await fs.readFile(./README.md, utf-8); // string const bytes await fs.readFile(./image.png); // Buffer2.2writeFile完整签名await fs.writeFile(file, data, options); // data 可以是 // string → 按 encoding 写入 // Buffer → 字节写入 // TypedArray / DataView → 字节写入 await fs.writeFile(./out.txt, hello\n, utf-8); await fs.writeFile(./out.bin, Buffer.from([0xff, 0xfe]));writeFile默认覆盖整个文件。要追加内容用appendFileawait fs.appendFile(./access.log, ${new Date().toISOString()} GET /\n);::: warningwriteFile不存在会创建存在会覆盖。对重要文件先用fs.access检查或直接用追加模式aflag更安全。:::2.3 常用 flag 一览flag含义r只读默认w写入不存在则创建存在则清空a追加不存在则创建r读写不存在则报错w读写不存在则创建存在则清空ax追加文件已存在则失败用于独占创建场景避免并发覆盖三、文件描述符File Descriptoropen/read/close三个底层调用组合出打开文件 → 读 N 字节 → 关闭的精细控制const fs require(node:fs/promises); const fd await fs.open(./big.txt, r); try { const buf Buffer.alloc(1024); // 1KB 缓冲区 let pos 0; while (true) { const { bytesRead } await fd.read(buf, 0, 1024, pos); if (bytesRead 0) break; process.stdout.write(buf.subarray(0, bytesRead)); pos bytesRead; } } finally { await fd.close(); }什么时候用 fd 而不是readFile场景推荐整个文件能装入内存readFile简洁大文件GB 级别流式处理createReadStream第 7 章部分读取读头 1KB 看 magic numberfd.read(buf, 0, len, position)频繁读小块 需要 seekfd四、文件信息查询查询文件元信息大小、时间戳、类型用fs.statconst fs require(node:fs/promises); const stats await fs.stat(./config.json); stats.isFile(); // 是否普通文件 stats.isDirectory(); // 是否目录 stats.size; // 字节数 stats.atime; // 上次访问 stats.mtime; // 上次修改内容 stats.ctime; // 上次修改元数据权限等 stats.birthtime; // 创建时间不保证可用 stats.atimeMs; // 毫秒时间戳用于计算fs.stat跟随符号链接要查链接本身用fs.lstat。五、目录操作目录的创建、读取、重命名、删除由一组 API 承担const fs require(node:fs/promises); // 创建recursive: true 等价于 mkdir -p await fs.mkdir(./a/b/c, { recursive: true }); // 读取目录条目 const entries await fs.readdir(./src); // entries 是 string[]Node 20 可加 { withFileTypes: true } 拿到 Dirent[] // 删除recursive: true 才能删非空目录Node 14.14 await fs.rm(./a, { recursive: true, force: true }); // 重命名 / 移动 await fs.rename(./old.txt, ./new.txt); // 读目录 过滤 const jsFiles (await fs.readdir(./src)) .filter((f) f.endsWith(.js));六、文件路径处理文件 I/O 几乎总要配合path模块避免字符串拼接const fs require(node:fs/promises); const path require(node:path); // ❌ 错误直接拼 const filePath __dirname /config/ filename; // ✅ 正确path.join const filePath path.join(__dirname, config, filename); // ✅ 跨平台os.homedir() path.join const userConfig path.join(os.homedir(), .myapp, config.json); // ✅ 读取 package.json 同目录的相对路径文件 const pkgDir path.dirname(require.resolve(./package.json));七、错误处理文件操作的错误类型固定可枚举常见的err.codecode含义ENOENT文件 / 目录不存在EACCES权限不足EISDIR当成文件打开目录ENOTDIR当成目录进入文件EEXIST文件已存在创建时EMFILE打开的文件描述符过多const fs require(node:fs/promises); async function readConfig() { try { return await fs.readFile(./config.json, utf-8); } catch (err) { if (err.code ENOENT) { // 配置文件不存在是预期情况用默认值 return {}; } if (err.code EACCES) { throw new Error(配置目录无读取权限); } throw err; // 其他错误继续上抛 } }::: tip不要吞掉错误码就 throw 一个字符串。保留err.code方便上游根据类型决策如ENOENT走默认配置EACCES走错误提示。:::八、并发读写同一文件多个fs调用并发操作同一文件Node 不保证原子性。例如两个writeFile并发后写的覆盖先写的且中间状态可能损坏文件// ❌ 危险两个 writeFile 并发 await Promise.all([ fs.writeFile(log.txt, A), fs.writeFile(log.txt, B), ]); // 结果不可预测可能是 A、B也可能是 BA 或损坏 // ✅ 方案 1用 appendFile追加模式POSIX 保证原子 await Promise.all([ fs.appendFile(log.txt, A), fs.appendFile(log.txt, B), ]); // ✅ 方案 2串行必要时 await fs.writeFile(log.txt, A); await fs.writeFile(log.txt, B);对大文件或频繁更新的场景文件 I/O 也不适合用 SQLite / Redis / 专门的日志库pino 日志聚合替代。九、文件锁Node没有内置文件锁。需要互斥时场景方案单进程内await串行调用 /fs.promises的串行队列多进程间proper-lockfile包分布式Redis / Zookeeper / etcd十、性能与最佳实践场景推荐反例启动期读配置readFileSync必须阻塞到读完才能继续用异步版本然后.then启动请求处理中读文件fs.promises.readFilereadFileSync阻塞事件循环大文件createReadStream见第 7 章readFile一次性读入内存批量小文件Promise.all([...])并发串行 await延迟叠加错误处理按err.code分支catch (e) { /* 静默 */ }路径拼接path.join字符串十一、小结fs提供同步 / 异步回调 / Promise 三套 API默认用 PromisereadFile/writeFile是最简单的读写大文件用createReadStream写文件注意 flagw覆盖、a追加、ax独占创建错误处理按err.code分支ENOENT/EACCES/EMFILE等并发写同一文件无原子保证要串行或用追加模式路径处理永远走path模块不要直接拼字符串
Node系列 · Node基础文件 I/ONode 的文件 I/O 几乎全靠fs模块。它同一份能力提供三套 API同步 / 异步回调 / Promise混用会产生事件循环被阻塞或回调金字塔问题。理解三者的取舍就能写好所有 Node 文件操作。一、fs 模块的三套 API同一个操作readFilefs提供三种写法风格函数返回阻塞主线程同步fs.readFileSync()数据 / 抛异常✅ 阻塞异步回调fs.readFile(cb)undefined / 通过 cb(err, data) 返回❌ 非阻塞Promisefs.promises.readFile()Promisedata / reject(err)❌ 非阻塞1.1 同步 APIconst fs require(node:fs); try { const data fs.readFileSync(./config.json, utf-8); console.log(JSON.parse(data)); } catch (err) { console.error(读取失败:, err.message); }1.2 异步回调 APIconst fs require(node:fs); fs.readFile(./config.json, utf-8, (err, data) { if (err) { console.error(读取失败:, err.message); return; } console.log(JSON.parse(data)); });回调第一个参数永远是err这是 Node 的错误优先回调约定。1.3 Promise API推荐const fs require(node:fs/promises); async function loadConfig() { try { const data await fs.readFile(./config.json, utf-8); return JSON.parse(data); } catch (err) { console.error(读取失败:, err.message); throw err; } } loadConfig().then((cfg) console.log(cfg));::: tip默认用 Promise 版本。它和 async/await 配合最自然错误用 try/catch 捕获与同步代码视觉上接近。同步版本只适合启动期必须串行的场景如读取配置文件初始化回调风格已基本被淘汰。:::二、读写文件2.1readFile完整签名// 异步 Promise 版 const buf await fs.readFile(path, options); // options 可以是 // string → utf-8 / hex / base64 / latin1 / ascii // object → { encoding, flag } // 省略 → 返回 Buffer不自动转字符串 const text await fs.readFile(./README.md, utf-8); // string const bytes await fs.readFile(./image.png); // Buffer2.2writeFile完整签名await fs.writeFile(file, data, options); // data 可以是 // string → 按 encoding 写入 // Buffer → 字节写入 // TypedArray / DataView → 字节写入 await fs.writeFile(./out.txt, hello\n, utf-8); await fs.writeFile(./out.bin, Buffer.from([0xff, 0xfe]));writeFile默认覆盖整个文件。要追加内容用appendFileawait fs.appendFile(./access.log, ${new Date().toISOString()} GET /\n);::: warningwriteFile不存在会创建存在会覆盖。对重要文件先用fs.access检查或直接用追加模式aflag更安全。:::2.3 常用 flag 一览flag含义r只读默认w写入不存在则创建存在则清空a追加不存在则创建r读写不存在则报错w读写不存在则创建存在则清空ax追加文件已存在则失败用于独占创建场景避免并发覆盖三、文件描述符File Descriptoropen/read/close三个底层调用组合出打开文件 → 读 N 字节 → 关闭的精细控制const fs require(node:fs/promises); const fd await fs.open(./big.txt, r); try { const buf Buffer.alloc(1024); // 1KB 缓冲区 let pos 0; while (true) { const { bytesRead } await fd.read(buf, 0, 1024, pos); if (bytesRead 0) break; process.stdout.write(buf.subarray(0, bytesRead)); pos bytesRead; } } finally { await fd.close(); }什么时候用 fd 而不是readFile场景推荐整个文件能装入内存readFile简洁大文件GB 级别流式处理createReadStream第 7 章部分读取读头 1KB 看 magic numberfd.read(buf, 0, len, position)频繁读小块 需要 seekfd四、文件信息查询查询文件元信息大小、时间戳、类型用fs.statconst fs require(node:fs/promises); const stats await fs.stat(./config.json); stats.isFile(); // 是否普通文件 stats.isDirectory(); // 是否目录 stats.size; // 字节数 stats.atime; // 上次访问 stats.mtime; // 上次修改内容 stats.ctime; // 上次修改元数据权限等 stats.birthtime; // 创建时间不保证可用 stats.atimeMs; // 毫秒时间戳用于计算fs.stat跟随符号链接要查链接本身用fs.lstat。五、目录操作目录的创建、读取、重命名、删除由一组 API 承担const fs require(node:fs/promises); // 创建recursive: true 等价于 mkdir -p await fs.mkdir(./a/b/c, { recursive: true }); // 读取目录条目 const entries await fs.readdir(./src); // entries 是 string[]Node 20 可加 { withFileTypes: true } 拿到 Dirent[] // 删除recursive: true 才能删非空目录Node 14.14 await fs.rm(./a, { recursive: true, force: true }); // 重命名 / 移动 await fs.rename(./old.txt, ./new.txt); // 读目录 过滤 const jsFiles (await fs.readdir(./src)) .filter((f) f.endsWith(.js));六、文件路径处理文件 I/O 几乎总要配合path模块避免字符串拼接const fs require(node:fs/promises); const path require(node:path); // ❌ 错误直接拼 const filePath __dirname /config/ filename; // ✅ 正确path.join const filePath path.join(__dirname, config, filename); // ✅ 跨平台os.homedir() path.join const userConfig path.join(os.homedir(), .myapp, config.json); // ✅ 读取 package.json 同目录的相对路径文件 const pkgDir path.dirname(require.resolve(./package.json));七、错误处理文件操作的错误类型固定可枚举常见的err.codecode含义ENOENT文件 / 目录不存在EACCES权限不足EISDIR当成文件打开目录ENOTDIR当成目录进入文件EEXIST文件已存在创建时EMFILE打开的文件描述符过多const fs require(node:fs/promises); async function readConfig() { try { return await fs.readFile(./config.json, utf-8); } catch (err) { if (err.code ENOENT) { // 配置文件不存在是预期情况用默认值 return {}; } if (err.code EACCES) { throw new Error(配置目录无读取权限); } throw err; // 其他错误继续上抛 } }::: tip不要吞掉错误码就 throw 一个字符串。保留err.code方便上游根据类型决策如ENOENT走默认配置EACCES走错误提示。:::八、并发读写同一文件多个fs调用并发操作同一文件Node 不保证原子性。例如两个writeFile并发后写的覆盖先写的且中间状态可能损坏文件// ❌ 危险两个 writeFile 并发 await Promise.all([ fs.writeFile(log.txt, A), fs.writeFile(log.txt, B), ]); // 结果不可预测可能是 A、B也可能是 BA 或损坏 // ✅ 方案 1用 appendFile追加模式POSIX 保证原子 await Promise.all([ fs.appendFile(log.txt, A), fs.appendFile(log.txt, B), ]); // ✅ 方案 2串行必要时 await fs.writeFile(log.txt, A); await fs.writeFile(log.txt, B);对大文件或频繁更新的场景文件 I/O 也不适合用 SQLite / Redis / 专门的日志库pino 日志聚合替代。九、文件锁Node没有内置文件锁。需要互斥时场景方案单进程内await串行调用 /fs.promises的串行队列多进程间proper-lockfile包分布式Redis / Zookeeper / etcd十、性能与最佳实践场景推荐反例启动期读配置readFileSync必须阻塞到读完才能继续用异步版本然后.then启动请求处理中读文件fs.promises.readFilereadFileSync阻塞事件循环大文件createReadStream见第 7 章readFile一次性读入内存批量小文件Promise.all([...])并发串行 await延迟叠加错误处理按err.code分支catch (e) { /* 静默 */ }路径拼接path.join字符串十一、小结fs提供同步 / 异步回调 / Promise 三套 API默认用 PromisereadFile/writeFile是最简单的读写大文件用createReadStream写文件注意 flagw覆盖、a追加、ax独占创建错误处理按err.code分支ENOENT/EACCES/EMFILE等并发写同一文件无原子保证要串行或用追加模式路径处理永远走path模块不要直接拼字符串
