稍候片刻,月出文自明。
exports 决定模块怎么加载;事件循环和微任务队列决定回调怎么排;await 和错误边界决定异常怎么冒泡;信号、退出码和优雅关闭决定进程怎么退。落到工程上,大文件用流并处理背压,生产优先选 LTS,提交依赖锁文件,CI 用 npm ci。具体 API 和版本差异查官方文档。$ node -v # v22.11.0
$ node -e "console.log(process.versions)" # v8 / uv / openssl 各自的版本都看得到
$ node # 进入 REPL,.exit 或 Ctrl+D 退出
$ node app.js
$ node --watch app.js # 改文件自动重启,18.11 引入,22 起稳定
$ node --env-file=.env app.js # 20.6 起内置读取 .env,不必再装 dotenv
$ node --test # 跑内置测试运行器,默认找 *.test.js// math.cjs
function add(a, b) { return a + b; }
module.exports = { add }; // 正确写法
// exports.add = add; // 也可以:挂在初始对象上
// exports = { add }; // 错误:只是重新绑定局部变量,导出还是空的
// app.cjs
const { add } = require('./math'); // 扩展名可省略,还会自动找 index.js
console.log(add(1, 2)); // 3
delete require.cache[require.resolve('./math')]; // 手动清缓存,热更新时才用// math.js(package.json 里有 "type": "module")
export function add(a, b) { return a + b; }
export default function sub(a, b) { return a - b; }
// app.js
import sub, { add } from './math.js'; // 相对路径必须写 .js
import { readFile } from 'node:fs/promises';
const text = await readFile('./a.txt', 'utf8'); // 顶层 await 只有 ESM 能用
const { default: pkg } = await import('./optional.js'); // 条件加载用动态 import()
import { fileURLToPath } from 'node:url';
const __dirname = fileURLToPath(new URL('.', import.meta.url)); // ESM 没有 __dirname{
"name": "my-lib",
"type": "module",
"exports": {
".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs" },
"./utils": "./dist/utils.js"
}
}setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
Promise.resolve().then(() => console.log('promise'));
process.nextTick(() => console.log('nextTick'));
console.log('sync');
// 输出:sync -> nextTick -> promise -> timeout / immediate
// 最后两个在顶层脚本里的顺序不固定,受进程启动耗时影响
import { readFile } from 'node:fs/promises';
await readFile(import.meta.url); // 处在 I/O 回调上下文
setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
// 这里 immediate 一定在 timeout 之前:此刻在 poll 阶段,下一步就是 checkimport { readFile } from 'node:fs';
readFile('./a.txt', 'utf8', (err, data) => {
if (err) return console.error(err.code); // 例如 'ENOENT'
console.log(data);
});
// 换成 promises 版 + async/await
import { readFile as readFileP } from 'node:fs/promises';
try {
const text = await readFileP('./a.txt', 'utf8');
} catch (err) {
if (err.code !== 'ENOENT') throw err; // 只处理预期的错误,其余继续抛
}// 并发,不是串行
const users = await Promise.all(ids.map(id => getUser(id)));
// 要全部结果、允许部分失败
const results = await Promise.allSettled(tasks);
// 限流:别一次开一万个连接
for (let i = 0; i < ids.length; i += 10) {
await Promise.all(ids.slice(i, i + 10).map(id => getUser(id)));
}
// 超时:AbortSignal.timeout 从 17.3 起可用
const res = await fetch(url, { signal: AbortSignal.timeout(3000) });import path from 'node:path';
path.join('/a', 'b', '../c'); // '/a/c'
path.resolve('a', 'b'); // '/当前工作目录/a/b'
path.dirname('/a/b/c.txt'); // '/a/b'
path.extname('/a/b/c.txt'); // '.txt'
path.join(process.cwd(), 'logs'); // 相对工作目录,不是相对脚本文件import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
const rl = createInterface({
input: createReadStream('big.log'),
crlfDelay: Infinity,
});
let lines = 0;
for await (const line of rl) lines++;
console.log(lines);
const a = Buffer.from('你好'); // 按 UTF-8 编码的字节
const b = Buffer.alloc(8); // 8 字节,全部清零
const c = Buffer.allocUnsafe(8); // 更快但不清零,可能残留旧内存数据,敏感场景别用import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';
import { createReadStream, createWriteStream } from 'node:fs';
await pipeline(
createReadStream('input.log'),
createGzip(),
createWriteStream('input.log.gz')
);
// 出错会 reject,并自动销毁沿途的流;只写 .pipe() 的话错误不会往下传const port = Number(process.env.PORT ?? 3000); // 环境变量都是字符串,记得转
process.exitCode = 1; // 比 process.exit(1) 安全
// process.exit() 会直接中断,管道里的 stdout 还没写完,日志就丢了const server = app.listen(3000);
let closing = false;
for (const sig of ['SIGTERM', 'SIGINT']) {
process.on(sig, () => {
if (closing) return;
closing = true;
server.close(() => process.exit(0)); // 不再接新连接,等在途请求结束
setTimeout(() => process.exit(1), 10_000).unref(); // 兜底:超时就硬退
});
}{
"type": "module",
"scripts": {
"dev": "node --watch src/server.js",
"test": "node --test"
},
"engines": { "node": ">=20" },
"dependencies": { "express": "^4.19.2" },
"devDependencies": { "typescript": "~5.6.3" }
}import { createServer } from 'node:http';
const server = createServer((req, res) => {
if (req.method === 'GET' && req.url === '/health') {
res.writeHead(200, { 'content-type': 'application/json' });
return res.end(JSON.stringify({ ok: true })); // 不调用 end,请求会一直挂着
}
res.writeHead(404, { 'content-type': 'text/plain' }).end('not found');
});
server.listen(3000, () => console.log('http://localhost:3000'));
// 端口被占用时会抛 Error: listen EADDRINUSE: address already in use :::3000// math.test.js
import test from 'node:test';
import assert from 'node:assert/strict';
import { add } from './math.js';
test('add 正常相加', () => {
assert.equal(add(1, 2), 3);
assert.deepEqual(add([1], [2]), [1, 2]);
});
// 运行:node --test
Node.js 基础知识点整理:运行时、模块、事件循环与工程化
Node 的笔记最容易散成一地碎片:fs 怎么读文件、EventEmitter 怎么用、中间件怎么串、npm 的那一堆依赖字段有什么区别。每个点都能单独背,但真写起服务还是会遇到「进程莫名其妙退了」「日志没打出来」「本地能跑上线就挂」这类问题。
这一篇按六条线重新归档:它是什么、模块怎么加载、事件循环怎么排、I/O 怎么读写、进程怎么活和退、包和工程怎么管。示例都能用 node 直接跑,输出写在注释里;涉及版本差异的地方我会标出引入的版本号——Node 迭代很快,具体行为以官方文档为准。
01|Node 是什么:一个运行时,不是语言也不是框架
Node.js 不发明语法,它只是把 JavaScript 放到服务端跑起来的宿主。拆开看是四块:V8 负责执行 JS;libuv 提供事件循环、线程池和跨平台 I/O;一批核心模块(fs、net、http、crypto……)把系统调用包成 JS API;外面则是 npm 生态。
「单线程」这句话经常被误解。准确的说法是:执行 JS 的线程只有一个,进程里还有别的线程。libuv 维护一个默认 4 个线程的线程池(可用环境变量 UV_THREADPOOL_SIZE 调整),文件读写、DNS 解析、crypto、zlib 这些任务在里面跑;网络 I/O 走 epoll / kqueue / IOCP,不占线程池。所以 Node 擅长的是「大量并发连接 + 少量计算」,代价是一旦有 CPU 密集任务压住主线程,所有请求都会排队等它。
02|先跑起来:版本、REPL 与常用启动参数
装 Node 推荐用版本管理器(nvm、fnm、volta),而不是从官网下载安装包覆盖——项目之间经常需要切版本。npm 随 Node 一起装好,pnpm/yarn 可以用 corepack 管。
process.versions 值得记住:线上排查时先确认 uv 和 openssl 的版本,很多「本地好好的」问题其实是运行时版本不一致。工程里再用 package.json 的 engines 字段把要求写死,配合 CI 校验。
03|模块系统:require 与 import 的分界线
Node 有两套模块系统,选哪套由文件形态决定:.cjs 或默认的 .js 走 CommonJS;.mjs 或 package.json 里写了 "type": "module" 之后,.js 走 ESM。
CommonJS 的关键是「运行时、同步、值拷贝」:require 是一个普通函数,加载完立刻返回;每个文件有自己的 module.exports,exports 只是它的初始引用,直接给 exports 赋值会断开这层关系。
ESM 的关键是「编译期、静态、只读视图」:import 会被提升到文件顶部,依赖关系在加载前就确定,所以不能写在 if 里;相对路径必须带扩展名;顶层可以 await。
互操作要记两条:ESM 里 import CommonJS 一直可行,默认导出就是 module.exports,具名导出靠静态分析推断,不保证全;反过来用 require() 加载 ESM 早年不行,近年的 Node(22.12 / 23 起默认)已经支持同步 ESM,更老的版本需要 --experimental-require-module。稳妥做法是一个包里别混用,需要同时支持两种调用方就用 exports 分出两个入口。
写了 exports 之后,包内没被列出的文件就不能被外部引用——它既是一张「导出地图」,也是一道围墙。顺带说一句 main 字段:它是老式入口,新包优先用 exports。
04|核心模块地图:常用 API 记位置就够
核心模块不用背 API,记住「哪个模块管什么」即可,细节现查文档。新版一律加 node: 前缀,能避免和 npm 上的同名包混淆(比如 node:test)。
05|事件循环:六个阶段和两个队列
libuv 的事件循环按阶段推进,每个阶段有自己的回调队列,走完一圈再回到 timers 开始下一轮:
阶段之外还有两个队列:process.nextTick 队列和 Promise 微任务队列。每执行完一个回调、每进入下一个阶段之前,都会先清空这两个队列,而且 nextTick 优先于 Promise。这就是「同步代码永远最先跑」的原因。
两个实践结论:setTimeout(fn, 0) 会被压到 1ms 左右,计时器只保证「不早于」而不保证精确,别用它做精确调度;更重要的是一条——不要在请求处理里写同步的重活。几百 MB 的 readFileSync、大文件 JSON.parse、深递归,都会把整条事件循环卡住,其它连接只能等。
06|异步三件套:回调、Promise、async/await
三种写法是同一件事的三层包装。回调时代约定「错误优先」:第一个参数是错误对象,成功时是 null。
错误处理有几条容易踩的线:try/catch 只能接住被 await 的 rejection,忘了 await 的 Promise 会绕过 catch;没人处理的 rejection 从 Node 15 起默认让进程退出;process.on('uncaughtException') 只能当日志兜底,进程状态此时已经不可信,正确做法是记完日志就退出,交给容器或进程管理器重启。
07|文件与路径:读写的第一层
path 里三个函数分工明确:join 拼路径并规范化,resolve 从右往左拼到绝对路径(相对当前工作目录),dirname/extname/basename 拆解路径。
读写文件先问「多大」:readFile 是一次性把整个文件读进内存,几百 MB 就会把内存和事件循环一起拖住;大文件用流,逐行处理用 readline。Buffer 是 Node 里的字节序列,继承自 Uint8Array,长度固定不能扩容;不传 encoding 时读出来就是 Buffer,传 'utf8' 才是字符串。
还有一个常被忽略的点:fs.writeFile 不是原子操作。多进程同时写同一个文件,或者写到一半进程被杀,都会留下半个文件。要安全就写临时文件再 fs.rename,同一分区内 rename 是原子的。
08|Stream 与背压:大数据的正确姿势
流有四种:可读(Readable)、可写(Writable)、双向(Duplex,比如 socket)、转换(Transform,比如 gzip)。它解决的是「数据比内存大」和「边产出边消费」。
背压是流的另一半价值:writable.write() 返回 false 表示缓冲区满了,应该等 drain 事件再继续写,否则内存会一路涨上去。pipeline 和 for await 已经替你处理了这件事,手写 on('data') 却没有处理背压,就是内存泄漏的常见来源。
09|进程:参数、环境变量与优雅退出
process 是 Node 暴露给脚本的那个「进程对象」,最常用的几个属性:argv(命令行参数,前两项是 node 路径和脚本路径)、env(环境变量,值永远是字符串)、cwd()(当前工作目录)、exitCode、memoryUsage()。
优雅退出是线上服务的必修课:收到 SIGTERM 后先停止接受新连接,把在途请求处理完再退出,并留一个兜底超时,防止永远等下去。
10|npm 与 package.json:依赖那点事
package.json 里真正影响运行时的字段不多:name/version、type(决定 .js 走 CJS 还是 ESM)、main/exports(入口)、scripts(命令)、engines(Node 版本要求)、files(发布时包含哪些文件)。其余大半是给依赖解析用的。
11|最小的 HTTP 服务与请求生命周期
把 http 这一层看懂,框架的中间件就不再神秘:它无非是把 (req, res) 依次传给一串函数,再决定什么时候 res.end()。
客户端方向:fetch 从 Node 18 起是全局的(实现是 undici),不用再装 node-fetch;Request、Response、Headers 也一并在全局。老代码里那些 http.request 的写法依然有效,只是更啰嗦。
12|测试、调试与性能观察
内置测试运行器从 Node 18 起可用,20 起标记稳定,配合 node:assert 足够覆盖大多数单元测试,不必为了跑几个断言引一整套框架。
13|常见坑自查清单
下面这些几乎每个 Node 项目都会碰到一次,出问题时先按这张表过一遍:
14|收个尾:先理顺四条线
Node 的 API 面很宽,但骨架只有四条:模块怎么加载(CJS/ESM 与 exports)、回调怎么排队(六个阶段加两个队列)、错误怎么冒泡(await、rejection、进程退出)、进程怎么活和退(信号、退出码、优雅关闭)。这四条理顺了,剩下的 fs、stream、crypto 都是查文档就能用的具体能力。
下一步建议按需深入:想写服务就看 http 与框架的中间件模型;想处理大数据就看流与背压;想榨性能就学 worker_threads 和 cluster;想稳就先把优雅退出和错误边界补齐。参考资料以 Node 官方文档(nodejs.org/api)和版本发布计划为准。