Node.js 文件系统、路径与 Stream 实战教程

本系列面向刚开始学习 Node.js 后端的开发者，运行环境以 Node.js 22、TypeScript、CommonJS 和 ts-node 为准。贯穿案例是：上传 Markdown ZIP，安全解压、转换为 HTML、重新压缩并返回。

学习路线

1. 学习路线与贯穿项目
2. 路径、文件和目录的基础模型
3. node:path 核心 API
4. Windows 与 Linux 路径差异
5. fs 回调、Promise 与同步 API
6. 文件与目录的日常操作
7. 文件句柄与资源生命周期
8. 文件权限与常见错误
9. 大文件与内存
10. Readable Stream
11. Writable Stream
12. Backpressure
13. pipe() 与错误边界
14. pipeline()
15. Transform 与 Duplex
16. 安全与原子文件写入
17. 安全路径与目录穿越
18. 符号链接、硬链接与竞态
19. 临时目录与文件清理
20. 大量文件的有限并发
21. 上传、下载与客户端中断
22. 文件操作日志与可观测性
23. Markdown ZIP 转换工程设计
24. 最终实战
25. API Cheatsheet

使用方法

每章先运行最小示例，再故意制造失败。文件系统代码只有在“不存在、无权限、磁盘满、客户端中断”时仍能正确释放资源，才算真正完成。

示例默认使用：

import path from "node:path";
import { readFile } from "node:fs/promises";

当前工程开启了 esModuleInterop，因此可使用 path 默认导入。若其他项目没有开启，应改用 import * as path from "node:path"。

核心原则

路径字符串不等于安全路径
读取完成不等于资源已经关闭
写入 finish 不等于物理介质绝对持久化
Stream 不等于零内存
错误处理必须覆盖清理和部分产物
ZIP 内部路径与操作系统路径必须分层处理