**这是本文档旧的修订版!**
Node.js 教程
Node.js 是基于 Chrome V8 引擎的 JavaScript 运行时,让 JS 可以脱离浏览器在服务端运行。 它的核心特征是 单线程 + 事件循环 + 非阻塞 I/O:不适合做重 CPU 计算,但非常擅长 I/O 密集型场景(Web API、命令行工具、网关、实时通信、构建脚本)。
1. 环境准备
- 安装:到 nodejs.org 下载 LTS 版本,生产环境优先用 LTS。
- 版本管理(推荐):
nvm(macOS/Linux)、fnm或nvm-windows,方便多版本切换。 npx随 npm 一起安装,可以直接运行包内命令,不用全局安装。
验证安装:
node -v npm -v
2. 第一个程序
- hello.js
const name = process.argv[2] || 'world'; console.log(`hello, ${name}`); console.log('Node 版本:', process.version);
运行:
node hello.js 小明
要点:process 是全局对象;process.argv 是命令行参数数组,前两项分别是 node 可执行文件路径和脚本路径,真正的参数从下标 2 开始。
3. 模块系统
Node.js 有两套模块体系,新项目建议直接用 ESM。
CommonJS(CJS,传统方式)
- math.js
function add(a, b) { return a + b; } module.exports = { add };
- main.js
const { add } = require('./math.js'); console.log(add(1, 2));
ES Modules(ESM,推荐)
在 package.json 里加 “type”: “module”,或把文件后缀写成 .mjs:
- math.mjs
export function add(a, b) { return a + b; }
- main.mjs
import { add } from './math.mjs'; console.log(add(1, 2));
注意几点:
- ESM 中
dirname不存在,用/filenameimport.meta.dirname/import.meta.url代替。 - ESM 的
import会被提升,且必须在顶层;需要动态导入用await import()。 - 同一个项目里 CJS 和 ESM 可以互操作,但 CJS 里不能直接
require纯 ESM 模块(新版可用require(esm),需注意版本兼容)。
4. npm 与 package.json
npm init -y # 生成 package.json npm install express # 安装依赖 npm install -D nodemon # 开发依赖 npm run dev # 执行 scripts 里的命令 npm ci # 按 lock 文件干净安装(CI 环境用)
package.json 关键字段:
| 字段 | 说明 |
|---|---|
type | module 表示用 ESM,默认 CJS |
main / exports | 包入口,exports 更现代、可控制子路径 |
dependencies | 运行时依赖 |
devDependencies | 只在开发/构建时需要的依赖 |
scripts | 可执行命令,npm run <名字> |
常识:
package-lock.json要提交到版本库,保证依赖版本一致。- 依赖锁版本、定期
npm audit与npm outdated检查。 - 不要提交
node_modules,用.gitignore排除。
5. 异步编程
Node.js 的性能来自异步,掌握异步是学 Node 的关键。三种写法按演进顺序:
- callback.js
// 1. 回调(老写法,容易回调地狱) fs.readFile('a.txt', 'utf8', (err, data) => { if (err) return console.error(err); console.log(data); });
- promise.js
// 2. Promise import { readFile } from 'node:fs/promises'; readFile('a.txt', 'utf8') .then((data) => console.log(data)) .catch((err) => console.error(err));
- async-await.js
// 3. async/await(推荐) import { readFile } from 'node:fs/promises'; try { const data = await readFile('a.txt', 'utf8'); console.log(data); } catch (err) { console.error('读取失败:', err.message); }
要点:
await只能在async函数内部或 ESM 顶层使用。- 并发要并行时用
Promise.all、Promise.allSettled,别在循环里无脑await(那是串行)。 - 未捕获的 Promise 拒绝在较新版本会直接让进程退出,务必处理错误。
6. 常用内置模块
| 模块 | 典型用途 |
|---|---|
node:fs/promises | 读写文件,readFile / writeFile / mkdir |
node:path | 路径拼接与解析,join / resolve / dirname |
node:url | URL 解析,URLSearchParams 处理查询串 |
node:http | 原生 HTTP 服务 |
node:os | 系统信息,cpus() / tmpdir() |
node:events | 事件总线,EventEmitter |
node:crypto | 哈希、随机数、加密 |
node:stream | 大文件/大数据流式处理 |
node:child_process | 调起子进程执行命令 |
读文件示例:
import { readFile, writeFile } from 'node:fs/promises'; import path from 'node:path'; const file = path.join(import.meta.dirname, 'data.json'); const json = JSON.parse(await readFile(file, 'utf8')); json.updatedAt = new Date().toISOString(); await writeFile(file, JSON.stringify(json, null, 2), 'utf8');
7. 写一个原生 HTTP 服务
- server.js
import http from 'node:http'; const server = http.createServer((req, res) => { if (req.url === '/health') { res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' }); return res.end(JSON.stringify({ ok: true })); } res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' }); res.end('Hello Node.js'); }); const port = process.env.PORT || 3000; server.listen(port, () => console.log(`listening on http://localhost:${port}`));
node server.js curl http://localhost:3000/health
8. 用 Express 快速搭接口
npm install express
- app.js
import express from 'express'; const app = express(); app.use(express.json()); app.get('/api/users/:id', (req, res) => { res.json({ id: req.params.id, name: '张三' }); }); app.post('/api/users', (req, res) => { res.status(201).json({ created: req.body }); }); // 统一错误处理:四个参数才会被识别为错误中间件 app.use((err, req, res, next) => { console.error(err); res.status(500).json({ error: 'internal error' }); }); app.listen(3000, () => console.log('http://localhost:3000'));
同类替代:Fastify、Koa、Hono。原生 http 偏底层,业务开发一般用框架。
9. 事件循环与性能要点
- 不要阻塞事件循环:同步 API(
readFileSync、crypto.pbkdf2Sync、大 JSON 解析、复杂正则)会卡住所有请求。 - 定时器、I/O 回调在宏任务队列,
Promise.then/queueMicrotask在微任务队列;微任务先清空。 - CPU 密集任务用
worker_threads或多进程(cluster、PM2)分摊。 - 大文件用
stream+pipeline,避免一次性读进内存。 - 内存泄漏排查:
node –inspect+ Chrome DevTools 的 Memory / Heap snapshot。
10. 环境变量与配置
npm install dotenv
import 'dotenv/config'; const db = process.env.DATABASE_URL;
.env不要提交,把模板写进.env.example。- 配置校验缺失的必填变量,启动即报错,别等到运行时才炸。
- 生产环境通常由平台/容器注入环境变量,不一定用
dotenv。
11. 开发体验:watch 与 test
node --watch app.js # 文件变更自动重启(Node 18.11+) node --test # 运行 node:test 测试
调试相关的启动参数(–inspect、断点、DevTools)单独放在下一节详解。
{
"scripts": {
"dev": "node --watch app.js",
"start": "node app.js",
"test": "node --test"
}
}
内置测试示例:
- math.test.js
import test from 'node:test'; import assert from 'node:assert/strict'; import { add } from './math.mjs'; test('add 相加', () => { assert.equal(add(1, 2), 3); });
12. Inspector:Node.js 的调试内核
inspector 到底是什么?
inspector 不是第三方工具,而是 Node.js 内置的调试与诊断基础设施。它由两部分组成:
- V8 Inspector:V8 引擎自带的调试器,能暂停 JS 执行、读变量、取调用栈;
node:inspector模块 + 协议服务端:Node.js 把 V8 Inspector 包装起来,对外暴露 Chrome DevTools Protocol(CDP),通过 WebSocket 提供调试能力。
所以一句话概括:inspector 是 Node.js 与调试器之间的标准接口。它和 Node.js 的关系可以这么看:
| 类比 | 浏览器 | Node.js |
| — | — | — |
| 运行时 | Chrome 渲染进程 | node 进程 |
| 调试内核 | V8 Inspector | 同一个 V8 Inspector |
| 对外协议 | CDP | CDP(一样) |
| 调试界面 | Chrome DevTools | Chrome DevTools / VS Code / node inspect |
正因为用的是同一套协议和设备面板,你在浏览器里怎么打断点,在 Node.js 里就怎么打。这也是为什么 Node.js 不需要额外安装调试插件——inspector 是随 Node.js 一起发布的。
注意区分两个容易混淆的东西:
–inspect是命令行开关,作用是“把 inspector 服务端打开并监听一个端口”;node:inspector是代码里可以 require 的模块,作用是“在程序内部编程式地开启会话、执行表达式”。
四种常见的调试方式
方式一:Chrome / Edge DevTools(最直观)
node --inspect app.js # Debugger listening on ws://127.0.0.1:9229/xxxxxxxx-...
然后在 Chrome 地址栏打开 chrome:inspect):
(Edge 为 edge:inspect
- 在 Configure 里确认有
localhost:9229; - 在 Remote Target 列表里点 inspect,或点 Open dedicated DevTools for Node。
之后就是熟悉的 Sources(断点)、Console、Call Stack、Scope、Performance(CPU Profile)、Memory(堆快照)。
方式二:VS Code 附加调试
在 .vscode/launch.json 里加 attach 配置,然后 F5 选择该配置:
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "Attach to Node",
"port": 9229,
"restart": true
}
]
}
也可以不用 attach,直接 launch:“request”: “launch”、“program”: “${workspaceFolder}/app.js”,IDE 会自动加上 –inspect。
方式三:内置 CLI 调试器 node inspect
不装任何东西,在终端里断点调试:
node inspect app.js
break app.js:12 # 或简写 sb(12) 在下一行断点
cont # 继续执行 c
next # 单步跳过 n
step # 单步进入 s
out # 跳出
repl # 进入交互式求值,打印变量
exec('user.name') # 直接求值
bt # 打印调用栈
restart # 重启
适合服务器上没有图形界面、或者用 SSH 连进去排查的场景。
方式四:代码里编程式使用 node:inspector
- inspect-open.js
import inspector from 'node:inspector'; // 在代码里打开调试端口(相当于运行时的 --inspect) inspector.open(9229, '127.0.0.1', false); // wait=true 表示等调试器连上再继续 console.log('inspector url:', inspector.url()); // 建一个会话,直接对进程求值 —— 可以做诊断脚本 const session = new inspector.Session(); session.connect(); session.post('Runtime.evaluate', { expression: 'process.memoryUsage()' }, (err, res) => { if (err) return console.error(err); console.log(res.result); session.disconnect(); });
这条路径的价值不在日常打断点,而在于做自诊断与自动化采集:例如暴露一个 /debug/eval 内部接口、导出堆快照、采集 CPU profile、或写质量检测脚本。
参数与常用配置
| 参数 | 作用 |
|---|---|
–inspect | 打开 inspector,监听 127.0.0.1:9229,不暂停 |
–inspect-brk | 同上,并在第一行代码前暂停,适合调试启动逻辑 |
–inspect-wait | 启动后等待调试器连接才继续(较新版本) |
–inspect=0.0.0.0:9229 | 指定地址与端口(远程调试用,见下方安全提示) |
–inspect-port=9300 | 只改端口,不启用调试 |
–cpu-prof / –heap-prof | 启动即采样,退出时写出 .cpuprofile / .heapprofile |
–enable-source-maps | 让 TS / 打包后的代码断点能对上原始源码 |
运行时给已经跑着的进程开 inspector(Linux/macOS):
kill -USR1 <pid> # 进程会打印 ws://127.0.0.1:9229/...
注意:这样打开的 inspector 无法再关闭,且 9229 端口只监听本机。
安全提示
- 调试端口等同于任意代码执行入口,绝不要暴露到公网。
- 远程排障用 SSH 端口转发,而不是
–inspect=0.0.0.0: <code bash> # 先在本机执行,转发远端 9229 到本地 9229 ssh -L 9229:127.0.0.1:9229 user@server # 服务器上 node –inspect app.js </code> - 生产环境默认不要开 inspector;需要排障时临时开、排完关。
调试之外:inspector 撑起来的一整套诊断能力
理解 inspector 之后,很多看起来独立的工具都是它的延伸:
- 内存泄漏:DevTools → Memory → Heap snapshot,对比两次快照看谁在增长;
- CPU 热点:DevTools → Performance 录制,或
node –cpu-prof; - 诊断报告:
process.report.writeReport()或node –report-on-signal导出 JSON(含堆栈、系统信息、libuv 句柄),进程卡死后很有用; - 异步调用栈:DevTools 里开启 async stack,看清 Promise 链从哪来。
13. 常见坑
require('fs')写成fs没装包 → 内置模块要加node:前缀更清晰。- 忘记
await:Promise 对象被当成数据打印出来。 return res.json(…)之后继续执行代码 → 用return及时结束分支。- 相对路径依赖启动目录:用
path.join(import.meta.dirname, …)基于文件定位。 - 端口占用
EADDRINUSE:换端口或结束旧进程。 - 依赖体积失控:能用内置能力(
fetch、fs/promises、node:test)就不加包。 –inspect时断点打不上:程序早就跑过去了,改用–inspect-brk从第一行停住。EADDRINUSE: 9229:上一个调试进程没退干净,先杀掉旧进程再启动。- 在
chrome:inspect里看不到进程:检查地址是不是localhost:9229、端口是否被防火墙挡、以及是否用了0.0.0.0之外的绑定。 ===== 14. 进阶方向 ===== * TypeScript + Node:tsx/ts-node直接跑,生产先编译或用 Node 原生类型剥离。 * 流与管道:stream.pipeline、背压处理、大批量数据导出。 * 实时通信:ws、socket.io。 * 数据层:pg、mysql2、prisma、drizzle。 * 部署:Docker 多阶段构建、PM2 进程守护、健康检查与优雅退出(SIGTERM时停止接收新请求、关闭连接池)。 * 可观测性:结构化日志(pino)、prom-client'' 指标、OpenTelemetry 链路。 ===== 小结 ===== 学习路径建议:异步 → 模块与 npm → http/fs 内置模块 → 框架写接口 → 工程化(测试、日志、部署)。 先把事件循环和 async/await 吃透,剩下的都是在这两者之上的工程实践。mdk height=560 color=#3c873a # Node.js ## 运行时基础 ### V8 引擎 + 单线程 + 事件循环 ### 非阻塞 I/O,擅长 I/O 密集 ### 安装 LTS / nvm / fnm ## 模块系统 ### CommonJS:require / module.exports ### ESM:import / export(推荐) ### 内置模块加 node: 前缀 ## npm 生态 ### package.json:type / scripts / exports ### dependencies vs devDependencies ### lock 文件要提交 ### npx 直接运行命令 ## 异步编程 ### 回调 → Promise → async/await ### Promise.all 并行 ### 错误必须捕获 ## 常用内置模块 ### fs/promises 文件读写 ### path 路径处理 ### http 原生服务 ### events / crypto / stream / child_process ## Web 开发 ### 原生 http.createServer ### Express / Fastify / Hono ### 中间件与统一错误处理 ## 性能与稳定 ### 不阻塞事件循环 ### 微任务优先于宏任务 ### worker_threads / cluster ### stream + pipeline ## Inspector 调试 ### 本质:V8 Inspector + CDP 协议 ### --inspect 开端口 / --inspect-brk 首行暂停 ### 界面:chrome://inspect、VS Code attach、node inspect ### node:inspector 模块:inspector.open / Session.post ### 已有进程:kill -USR1 <pid> ### 安全:只绑 127.0.0.1,远程走 SSH 转发 ### 扩展:Heap snapshot、CPU profile、process.report ## 工程化 ### dotenv 环境变量 ### node --watch / node --test ### TypeScript + --enable-source-maps ### Docker 部署与优雅退出 ## 常见坑 ### 漏写 await ### 相对路径依赖启动目录 ### EADDRINUSE(3000 端口 / 9229 调试端口) ### --inspect 不暂停导致断点打不上 ### 依赖膨胀