一个上传接口按字符数限制长度,规则是「最多 100 个字符」。前端用 JS 的 str.length 校验,后端用 Node 再校验一次,结果明明只有 50 个汉字,后端却拒绝了。查下来,后端用的是 Buffer.byteLength(str),而业务规则里的「字符」和字节数根本不是一回事。
另一个更常见的场景是读文件:
const text = fs.readFileSync(path);
console.log(text.slice(0, 10));
打印出来不是字符串,而是一串十六进制和乱码。因为没传 encoding,fs.readFileSync 返回的是 Buffer,一个字节容器,不是字符串。对它调 slice 切的是字节,不是字符,中文很可能被从中间切断。
这两个问题的根源是同一个:Node 的很多 API 在「字节」和「字符」之间来回切换,默认值又不总是你期待的那个。这篇把 Buffer、path、fs、process 四组最常用的接口讲清楚,重点是默认值和边界。
Buffer:字节容器,不是字符串
Buffer 是 Node 用来处理二进制数据的对象,底层是一块固定长度的内存,按字节寻址。它继承自 Uint8Array,所以能下标访问、能切片、能被流读写。Buffer.from("中文") 默认按 UTF-8 编码,一个汉字三个字节,.length 是 6,而字符串的 "中文".length 是 2。
const b = Buffer.from('中文');
console.log(b.toString('hex'));
console.log(b.length, '中文'.length, Buffer.byteLength('中文'));
e4b8ade69687
6 2 6
所以「字符数限制」要用字符串长度或按 Unicode 码点计数,「字节数限制」才用 Buffer.byteLength。文件大小、网络包、数据库字段长度通常按字节,用户可见的字数通常按字符。两者混用,多语言内容一定出问题。
toString 支持多种编码:utf8、hex、base64、latin1 等。base64 常用于把二进制塞进 JSON 或 URL,hex 常用于日志和调试。注意 latin1 是「每个字节映射到一个字符」,不做多字节解码,用它读 GBK 文本只会得到乱码而不是报错,这一点和 Python 的 latin1 一样。
创建 Buffer 有三种常用方式:Buffer.from(...) 从字符串、数组或另一个 Buffer 复制;Buffer.alloc(n) 分配并清零;Buffer.allocUnsafe(n) 分配但不清零,速度快,可能包含旧内存残留。处理敏感数据不要用 allocUnsafe,省下的那点时间不值得冒泄露风险。
slice 和 subarray 都是「共享同一块内存」,不是复制。改切片会影响原 Buffer。我本机打印一个 6 字节 Buffer 的 byteOffset 是 256,buffer.byteLength 是 65536,因为它来自 Node 内部的内存池。需要独立副本时用 Buffer.from(buf) 或 Buffer.alloc 再 copy,别以为切片就是拷贝。
Buffer.concat(list) 把多个 Buffer 拼成一个,长度要自己算或让它自动算。拼接大量小 Buffer 时,先收集再一次性 concat,比循环里反复 Buffer.concat([a, b]) 快得多。后者每次都会分配新内存并复制,数据量大时是明显的性能坑。
字节被切断这件事,字符串层面看不出来,只有解码时才暴露。我本机把 Buffer.from('中文测试') 切前 4 个字节再 toString('utf8'),得到 "中�",末尾那个替换字符就是被切掉一半的「文」。StringDecoder 专门处理这种跨块边界:同样的前 4 个字节,第一次 write 只输出 "中",剩下的半个字符留在内部,第二次 write 拼上后输出 "文测试"。分块读文本时用它,别直接对每块调 toString。
Buffer 还提供 equals、compare、indexOf。我实测两个内容相同的 Buffer equals 返回 true,indexOf('bc') 返回 1,Buffer.compare(Buffer.from('a'), Buffer.from('b')) 返回 -1。比较二进制内容不要先转字符串再比,编码不同的同一段字节转出来可能一样,equals 按字节比较,最可靠。
base64 有个容易忽略的点:toString('base64') 会补 = 让长度对齐,解码时 Buffer.from(str, 'base64') 不校验内容,遇到非法字符会静默跳过而不是报错。所以「base64 解码成功」不代表「原始数据合法」,需要完整性校验时得另加摘要或长度检查。
path:拼接、解析与平台差异
path 模块处理文件路径的字符串,不访问文件系统。常用方法有 join、resolve、relative、parse、format、dirname、basename、extname。它们只做字符串运算,速度快,也不会因为文件不存在而失败。
console.log(path.join('a', '..', 'b'));
console.log(path.resolve('.'));
console.log(path.parse('/tmp/a/b.txt'));
console.log(path.relative('/tmp/a', '/tmp/a/b/c.txt'));
b
C:\project\docs
{ root: '/', dir: '/tmp/a', base: 'b.txt', ext: '.txt', name: 'b' }
b\c.txt
join 把片段拼起来并归一化,.. 会被消掉;resolve 从当前工作目录(或传入的基准目录)出发,算出绝对路径;relative 算两个路径之间的相对关系。注意 relative 的结果在 Windows 上用反斜杠,在 Linux 上用斜杠,跨平台传输路径字符串时要么统一成 /,要么只在本地使用。
parse 把路径拆成 root、dir、base、ext、name,format 反向拼回去。取扩展名用 extname,取文件名用 basename,取目录用 dirname。不要用字符串 split(".") 取后缀,文件名里可能有点,路径里可能有目录名带点。
跨平台时用 path.posix 和 path.win32 显式指定规则。比如生成 URL 路径、处理容器内的 Linux 路径,用 path.posix 就不受运行平台影响。默认的 path 跟随当前系统,本地测试和服务器行为可能不同。
extname 也有边界。我实测 path.extname('a.tar.gz') 是 .gz,path.extname('noext') 和 path.extname('.bashrc') 都是空字符串。它只认「最后一个点之后」的一段,.bashrc 这类隐藏文件没有扩展名。path.isAbsolute('C:/a') 在 Windows 上是 true,path.isAbsolute('./a') 是 false;path.normalize('a//b/../c') 得到 a\c。这些结果都随平台变,判断绝对路径别用 startsWith('/')。
join 和 resolve 对「后面的参数是绝对路径」处理不同。path.posix.join('/a', '/b') 得到 /a/b,把第二段当普通片段拼接;path.posix.resolve('/a', '/b') 得到 /b,遇到绝对路径就丢弃前面的。用户传入的路径片段直接拼进 join,如果片段以 / 开头,结果可能不是你预期的目录。拼之前先确认每段是「目录名」还是「完整路径」。
path.resolve() 依赖「当前工作目录」,不是「脚本所在目录」。用不同目录启动同一个脚本,resolve('.') 的结果会变。要基于脚本定位,用 __dirname(CJS)或 import.meta.dirname(ESM,较新版本支持),再交给 path.join。fs:同步、回调、Promise 三种写法
fs 的接口有三套风格。同步版以 Sync 结尾,比如 readFileSync,直接返回结果,失败抛异常;回调版接收 (err, data),不抛异常;Promise 版在 fs/promises 里,用 await 和 try/catch。三套做的是同一件事,区别在错误处理和阻塞方式。
读文本一定要传编码。不传返回 Buffer,传 'utf8' 返回字符串。写文件同理,传了编码才按文本写。二进制文件(图片、压缩包)不要传编码,保持 Buffer。这个默认值和 Python 的 open 不同:Python 文本模式返回字符串,Node 默认给你字节。
const text = await fs.readFile(file, 'utf8');
await fs.writeFile(out, text, 'utf8');
await fs.mkdir(dir, { recursive: true });
const st = await fs.stat(file);
console.log(st.size, st.isFile(), st.mtime instanceof Date);
目录操作注意 recursive: true,否则父目录不存在会报 ENOENT。readdir 加 withFileTypes: true 能直接拿到 Dirent,用 isFile()、isDirectory() 判断类型,比再 stat 每个文件省事。stat 返回的 mtime 是 Date 对象,可以直接比较。
错误对象上有 code、errno、syscall、path 这几个字段。我实测读不存在的文件,打印出来是 ENOENT -4058 open C:\...\missing.txt。Windows 的 errno 是负数,Linux 上是正数,所以判断错误类型要看 code,不要比较 errno。按 code 分支处理,跨平台才稳。
existsSync 只返回布尔,吞掉了错误原因,而且「检查完再操作」之间有竞态。更好的做法是直接操作并捕获 ENOENT,需要区分「文件不存在」和「没权限」时,错误对象会告诉你。access 可以检查权限,但它同样有竞态,别把它当成安全边界。
appendFile、rename、open 这些接口同样有 Promise 版。我实测先写 line1\n 再 appendFile 追加 line2\n,读回来是两行完整内容;rename 之后目录里只剩 b.txt;用 fs.open 拿到句柄再 read,读 8 个字节返回 "line1\nli"。open 拿到的句柄必须 close,忘了关就是文件描述符泄漏,进程跑久了会报 EMFILE: too many open files。只用 readFile 这类一站式接口不需要自己管句柄。
readdir 默认返回字符串数组,加 withFileTypes: true 返回 Dirent。类型信息来自目录项本身,不用再对每个文件 stat,速度快;但它不跟随符号链接,遇到链接要自己判断。要拿大小和时间还是得 stat,两者分工不同。
writeFile 不是原子操作。它先截断再写,写到一半进程崩了,文件就只剩半截。需要原子替换时,先写临时文件再 rename,同一文件系统内的 rename 是原子的。日志追加用 appendFile,别用「读出来、拼上、写回去」,并发会丢数据。
读大文件不要用 readFile。它一次性分配「文件大小」那么多内存,几百 MB 的文件直接把 RSS 顶上去,几个并发就 OOM。这时候要用 createReadStream 分块读,下一篇细讲。判断标准很简单:文件大小超过可用内存的十分之一,或者要同时处理多个文件,就别用一次性读取。
同步版在启动阶段用没问题,放到请求处理路径上就是灾难。假设一个请求里用 readFileSync 读 10 MB 文件,耗时几十毫秒,这段时间整个进程不能处理任何其他请求,并发一上来就排队。可以用 process.hrtime.bigint() 或 console.time 量一下同步调用的耗时,超过几毫秒的就该考虑换异步。
编码也要确认。readFile(file, 'utf8') 假定文件是 UTF-8,实际可能是 GBK,或者带 BOM 的 UTF-8。BOM 会让第一个字段多出不可见字符,比较字符串时莫名不相等。读外部文件前先确认编码,必要时去掉 BOM,别默认「文本就是 UTF-8」。
process:进程信息与退出
process 是全局对象,不用导入。常用属性有 argv、env、cwd()、platform、arch、version、pid、memoryUsage()。argv 第一个是 node 可执行文件路径,第二个是脚本路径,后面才是用户参数。env 是环境变量对象,读不存在的键返回 undefined。
console.log(process.argv.slice(2));
console.log(process.env.NODE_ENV);
console.log(process.memoryUsage());
我本机空环境打印 process.env.NODE_ENV 是 undefined,memoryUsage() 返回 rss、heapTotal、heapUsed、external、arrayBuffers 五项,单位是字节。看内存不要只看 heapUsed,Buffer 和外部内存算在 external 里,RSS 才是进程实际占用的物理内存。
这三个数字要分开读:只涨 rss 不涨 heapUsed,通常是 Buffer 或原生内存;heapUsed 持续上涨才是 JS 对象没释放;external 涨得快,八成是创建了大量 Buffer 没释放引用。排查前先换算单位,rss 到几百万字节其实只有几 MB,不要被数字吓到。
process.cwd() 是启动时的工作目录,__dirname 是脚本所在目录,从别的目录启动脚本时两者会分开。命令行参数也不要手写解析:-- 之后的内容、带 = 的长参数、可重复的短参数都有约定,自己拆字符串很容易错。环境变量全是字符串,process.env.PORT 拿到的是 "8080" 而不是数字,用之前要转换。
退出用 process.exitCode = 1 比 process.exit(1) 安全。前者只是设置退出码,让当前事件循环把该做的事做完;后者立即终止进程,未写完的日志、未关闭的连接都会丢。只有在「必须马上停」的场景才用 exit。我实测设置 exitCode 后进程正常结束,命令行拿到的退出码是 3。
信号处理用 process.on('SIGINT', ...) 等。收到信号后要做清理,然后显式退出;不处理的话,默认行为是直接终止。容器环境里 SIGTERM 是常见的停止信号,服务要能在收到后关闭连接、保存状态,再退出。超时没退出会被强制杀掉,清理逻辑就白写了。
exit 事件里只能做同步操作。我实测在 exit 回调里写 setTimeout,那段代码永远不会执行,因为事件循环已经停了。需要异步清理(比如把缓冲区刷到磁盘),放在 beforeExit 里,它会在事件循环空了但还没退出时触发。顺序是 beforeExit 先于 exit,两者都不要做耗时操作。
环境变量在 Windows 上不区分大小写,PATH 和 Path 是同一个键;Linux 上区分。写跨平台脚本时读环境变量统一用大写约定,别依赖某个平台的大小写行为。另外 env 里的值永远是字符串,布尔配置也要写成 "true" / "false" 再解析。
process.nextTick、setImmediate、queueMicrotask 都属于调度 API,具体顺序放到事件循环那篇讲。这里只需要记住:process.nextTick 不是「下一个时间片」,它比 Promise 微任务还优先,递归调用会饿死 I/O。
日志里带上 process.pid,排查多进程问题时能分清是哪个实例写的;process.title 改了之后,系统监控里能直接看到业务名而不是 node。这两个都是小便利,真出问题时省不少来回找的功夫。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
读文件得到乱码或 <Buffer ...> | 没传 encoding,拿到的是字节 | 文本读 utf8,二进制保持 Buffer |
| 中文字符数校验不准 | 把字节数当成字符数 | 确认规则单位,字符用 length,字节用 byteLength |
| 切片后原 Buffer 也变了 | slice 和 subarray 共享内存 | 需要独立副本时用 Buffer.from 复制 |
| Buffer 里出现旧数据 | 用了 allocUnsafe 且没清零 | 敏感场景改用 Buffer.alloc |
| 相对路径指向了意外目录 | resolve 基于当前工作目录 | 用 __dirname 或 import.meta.dirname 定位 |
| Windows 正常、Linux 报路径错 | 手拼了反斜杠或假定了大小写 | 统一用 path.join,跨端路径用 path.posix |
创建目录报 ENOENT | 父目录不存在且没加 recursive | 加 { recursive: true } |
错误处理按 errno 判断失效 | 不同平台 errno 数值不同 | 按 err.code 判断,比如 ENOENT |
| 设置退出码后进程没停 | exitCode 只影响退出码,不会立即结束 | 确认事件循环是否还有未完成的句柄 |
边界与代价
Buffer 的代价是「它不是字符串」。所有字符串方法在 Buffer 上都不适用,长度、下标、切片全部按字节。把 Buffer 当字符串用,短文本可能看不出问题,中文、emoji、组合字符一上来就露馅。处理文本前先解码,处理完再编码,中间不要混着操作。
path 的代价是「它只算字符串,不验证真实性」。path.join 不会告诉你目录存不存在,resolve 不会检查权限。路径安全和文件系统状态是两回事,前者靠规范化和白名单校验,后者靠实际操作的错误。把两者混在一起,容易出现「校验通过但操作失败」或「操作成功但路径越界」。
fs 的代价是「三种风格混用会乱」。同一个文件,有的地方同步读、有的地方 Promise 读、有的地方回调读,错误处理方式不统一,排查时要在三种语义之间切换。项目里约定一种主风格,边界处再转换,比到处混用清楚。
process 的代价是「全局可变状态」。改 env、改 exitCode、注册信号监听,都会影响整个进程。测试里修改环境变量要记得恢复,多个模块同时监听同一个信号要协调好顺序。全局对象方便,但也最容易制造隐式耦合。
最后是平台边界。路径分隔符、大小写敏感、换行符、文件锁、errno 数值,Windows 和 Linux 都有差异。CI 里至少跑一个目标平台,比上线后才发现便宜。Node 已经封装了大部分差异,但前提是你用它的 API,而不是自己拼字符串。
小结
Buffer 是字节容器,长度按字节算,字符串长度按字符算,切片共享内存;path 只做字符串运算,join 拼接、resolve 转绝对路径、parse 拆解,跨平台用 path.posix 显式指定;fs 有同步、回调、Promise 三套接口,文本读写传编码,错误按 code 判断;process 提供参数、环境变量、内存和退出控制,改退出码用 exitCode,不要随手 exit。
这些 API 的共同点是「默认值有含义」。默认返回 Buffer、默认相对当前目录、默认不清零内存,每一个都需要知道,而不是背方法名。
当天可以自己验证的练习:
- 用
Buffer.from('中文')打印 hex、length和Buffer.byteLength,和字符串length对比。 - 创建一个 Buffer,切片后改一个字节,打印原 Buffer,确认它们共享内存。
- 用
path.parse拆一个带多级目录和多个点的文件名,再用format拼回去。 - 用 Promise 版
fs读一个不存在的文件,打印err.code、errno、err.path。 - 设置
process.exitCode = 3,运行后检查命令行退出码,再对比process.exit(3)的行为。
下一篇讲文件与流:stream、背压、大文件怎么读不炸内存。这一篇里的 readFile 会把整个文件装进内存,文件小的时候很方便,文件大了就要换流。流的核心不是 API,是「生产者和消费者的速度不匹配时怎么办」,下一篇用实测的背压现象讲清楚。