**这是本文档旧的修订版!**
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. 调试与开发体验
node --watch app.js # 文件变更自动重启(Node 18.11+) node --inspect app.js # 打开调试协议,浏览器 chrome://inspect 连接 node --test # 运行 node:test 测试
{
"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. 常见坑
require('fs')写成fs没装包 → 内置模块要加node:前缀更清晰。- 忘记
await:Promise 对象被当成数据打印出来。 return res.json(…)之后继续执行代码 → 用return及时结束分支。- 相对路径依赖启动目录:用
path.join(import.meta.dirname, …)基于文件定位。 - 端口占用
EADDRINUSE:换端口或结束旧进程。 - 依赖体积失控:能用内置能力(
fetch、fs/promises、node:test)就不加包。
13. 进阶方向
- 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 吃透,剩下的都是在这两者之上的工程实践。