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
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。
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);
});
  • require('fs') 写成 fs 没装包 → 内置模块要加 node: 前缀更清晰。
  • 忘记 await:Promise 对象被当成数据打印出来。
  • return res.json(…) 之后继续执行代码 → 用 return 及时结束分支。
  • 相对路径依赖启动目录:用 path.join(import.meta.dirname, …) 基于文件定位。
  • 端口占用 EADDRINUSE:换端口或结束旧进程。
  • 依赖体积失控:能用内置能力(fetch、fs/promises、node:test)就不加包。
  • 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 吃透,剩下的都是在这两者之上的工程实践。

# 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
## 工程化
### dotenv 环境变量
### node --watch / --inspect
### node:test 内置测试
### TypeScript 与 Docker 部署
## 常见坑
### 漏写 await
### 相对路径依赖启动目录
### EADDRINUSE 端口占用
### 依赖膨胀

该主题尚不存在

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

  • nodejs.1792210574.txt.gz
  • 最后更改: 2026/10/17 12:16
  • 由 张叶安