目录

Node.js 教程

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

1. 环境准备

验证安装:

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));

注意几点:

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 <名字>

常识:

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);
}

要点:

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 快速搭接口

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

9. 事件循环与性能要点

10. 环境变量与配置

npm install dotenv
import 'dotenv/config';
 
const db = process.env.DATABASE_URL;

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 内置的调试与诊断基础设施。它由两部分组成:

所以一句话概括: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 一起发布的。

注意区分两个容易混淆的东西:

四种常见的调试方式

方式一:Chrome / Edge DevTools(最直观)

node --inspect app.js
# Debugger listening on ws://127.0.0.1:9229/xxxxxxxx-...

然后在 Chrome 地址栏打开 chrome:inspect(Edge 为 edge:inspect):

之后就是熟悉的 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 端口只监听本机。

安全提示

调试之外:inspector 撑起来的一整套诊断能力

理解 inspector 之后,很多看起来独立的工具都是它的延伸:

13. 常见坑