Node.js 教程

Node.js 是基于 Chrome V8 引擎的 JavaScript 运行时,让 JS 可以脱离浏览器在服务端运行。 它的核心特征是 单线程 + 事件循环 + 非阻塞 I/O:不适合做重 CPU 计算,但非常擅长 I/O 密集型场景(Web API、命令行工具、网关、实时通信、构建脚本)。

  • 安装:到 nodejs.org 下载 LTS 版本,生产环境优先用 LTS。
  • 版本管理(推荐):nvm(macOS/Linux)、fnm 或 nvm-windows,方便多版本切换。
  • npx 随 npm 一起安装,可以直接运行包内命令,不用全局安装。

验证安装:

node -v
npm -v
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 开始。

Node.js 有两套模块体系,新项目建议直接用 ESM。

math.js
function add(a, b) {
  return a + b;
}
 
module.exports = { add };
main.js
const { add } = require('./math.js');
 
console.log(add(1, 2));

在 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 / filename 不存在,用 import.meta.dirname / import.meta.url 代替。
  • ESM 的 import 会被提升,且必须在顶层;需要动态导入用 await import()。
  • 同一个项目里 CJS 和 ESM 可以互操作,但 CJS 里不能直接 require 纯 ESM 模块(新版可用 require(esm),需注意版本兼容)。
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 排除。

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 拒绝在较新版本会直接让进程退出,务必处理错误。
模块 典型用途
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');
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

Express 是 Node.js 生态里最主流的 Web 框架,核心只有「路由 + 中间件」两件事。 完整教程见 Express 教程(安装与项目结构、路由与 Router 模块化、req/res、中间件洋葱模型、统一错误处理、zod 校验、JWT 认证、multer 上传、supertest 测试、生产部署、Express 5 变化)。下面先给一个最小可跑示例。

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 偏底层,业务开发一般用框架。

  • 不要阻塞事件循环:同步 API(readFileSync、crypto.pbkdf2Sync、大 JSON 解析、复杂正则)会卡住所有请求。
  • 定时器、I/O 回调在宏任务队列,Promise.then / queueMicrotask 在微任务队列;微任务先清空。
  • CPU 密集任务用 worker_threads 或多进程(cluster、PM2)分摊。
  • 大文件用 stream + pipeline,避免一次性读进内存。
  • 内存泄漏排查:node –inspect + Chrome DevTools 的 Memory / Heap snapshot(原理与用法见第 12 节 Inspector)。
npm install dotenv
import 'dotenv/config';
 
const db = process.env.DATABASE_URL;
  • .env 不要提交,把模板写进 .env.example。
  • 配置校验缺失的必填变量,启动即报错,别等到运行时才炸。
  • 生产环境通常由平台/容器注入环境变量,不一定用 dotenv。
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);
});

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 的模块,作用是“在程序内部编程式地开启会话、执行表达式”。
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(堆快照)。

在 .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。

不装任何东西,在终端里断点调试:

node inspect app.js
break app.js:12     # 或简写 sb(12) 在下一行断点
cont                # 继续执行 c
next                # 单步跳过 n
step                # 单步进入 s
out                 # 跳出
repl                # 进入交互式求值,打印变量
exec('user.name')   # 直接求值
bt                  # 打印调用栈
restart             # 重启

适合服务器上没有图形界面、或者用 SSH 连进去排查的场景。

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 之后,很多看起来独立的工具都是它的延伸:

  • 内存泄漏:DevTools → Memory → Heap snapshot,对比两次快照看谁在增长;
  • CPU 热点:DevTools → Performance 录制,或 node –cpu-prof;
  • 诊断报告:process.report.writeReport() 或 node –report-on-signal 导出 JSON(含堆栈、系统信息、libuv 句柄),进程卡死后很有用;
  • 异步调用栈:DevTools 里开启 async stack,看清 Promise 链从哪来。
  • 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 内置模块 → 框架写接口 → 调试(inspector)→ 工程化(测试、日志、部署)。 先把事件循环和 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(完整教程见 express 页面) #### 本质:路由 + 中间件两件事 #### 中间件洋葱模型:顺序、next()、next(err) #### 路由:方法 + 路径参数 + query + Router 模块化 #### req / res 常用 API #### 四参数统一错误处理 + 404 兜底 #### express.json 解析 body + zod 参数校验 #### 生态:helmet / cors / morgan / rate-limit / multer #### 分层:routes → controllers → services #### 生产:trust proxy、优雅退出、supertest 测试 #### Express 5:/*splat 通配、async 错误自动捕获 ### Fastify / Koa / 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 不暂停导致断点打不上 ### 依赖膨胀

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • nodejs.txt
  • 最后更改: 2026/11/10 17:14
  • 由 张叶安