差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 后一修订版 | 前一修订版 | ||
| nodejs [2026/10/17 12:13] – 创建 张叶安 | nodejs [2026/11/10 17:14] (当前版本) – 思维导图扩充 Express 子节点 张叶安 | ||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | 1 | + | ====== Node.js 教程 ====== |
| + | |||
| + | Node.js 是基于 Chrome V8 引擎的 JavaScript **运行时**,让 JS 可以脱离浏览器在服务端运行。 | ||
| + | 它的核心特征是 **单线程 + 事件循环 + 非阻塞 I/ | ||
| + | |||
| + | ===== 1. 环境准备 ===== | ||
| + | |||
| + | * 安装:到 [[https:// | ||
| + | * 版本管理(推荐):'' | ||
| + | * '' | ||
| + | |||
| + | 验证安装: | ||
| + | |||
| + | <code bash> | ||
| + | node -v | ||
| + | npm -v | ||
| + | </ | ||
| + | |||
| + | ===== 2. 第一个程序 ===== | ||
| + | |||
| + | <code javascript hello.js> | ||
| + | const name = process.argv[2] || ' | ||
| + | |||
| + | console.log(`hello, | ||
| + | console.log(' | ||
| + | </ | ||
| + | |||
| + | 运行: | ||
| + | |||
| + | <code bash> | ||
| + | node hello.js 小明 | ||
| + | </ | ||
| + | |||
| + | 要点:'' | ||
| + | |||
| + | ===== 3. 模块系统 ===== | ||
| + | |||
| + | Node.js 有两套模块体系,新项目建议直接用 ESM。 | ||
| + | |||
| + | ==== CommonJS(CJS,传统方式) ==== | ||
| + | |||
| + | <code javascript math.js> | ||
| + | function add(a, b) { | ||
| + | return a + b; | ||
| + | } | ||
| + | |||
| + | module.exports = { add }; | ||
| + | </ | ||
| + | |||
| + | <code javascript main.js> | ||
| + | const { add } = require(' | ||
| + | |||
| + | console.log(add(1, | ||
| + | </ | ||
| + | |||
| + | ==== ES Modules(ESM,推荐) ==== | ||
| + | |||
| + | 在 '' | ||
| + | |||
| + | <code javascript math.mjs> | ||
| + | export function add(a, b) { | ||
| + | return a + b; | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | <code javascript main.mjs> | ||
| + | import { add } from ' | ||
| + | |||
| + | console.log(add(1, | ||
| + | </ | ||
| + | |||
| + | 注意几点: | ||
| + | |||
| + | * ESM 中 '' | ||
| + | * ESM 的 '' | ||
| + | * 同一个项目里 CJS 和 ESM 可以互操作,但 CJS 里不能直接 '' | ||
| + | |||
| + | ===== 4. npm 与 package.json ===== | ||
| + | |||
| + | <code bash> | ||
| + | npm init -y # 生成 package.json | ||
| + | npm install express | ||
| + | npm install -D nodemon | ||
| + | npm run dev # 执行 scripts 里的命令 | ||
| + | npm ci # 按 lock 文件干净安装(CI 环境用) | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | ^ 字段 ^ 说明 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | 常识: | ||
| + | |||
| + | * '' | ||
| + | * 依赖锁版本、定期 '' | ||
| + | * 不要提交 '' | ||
| + | |||
| + | ===== 5. 异步编程 ===== | ||
| + | |||
| + | Node.js 的性能来自异步,掌握异步是学 Node 的关键。三种写法按演进顺序: | ||
| + | |||
| + | <code javascript callback.js> | ||
| + | // 1. 回调(老写法,容易回调地狱) | ||
| + | fs.readFile(' | ||
| + | if (err) return console.error(err); | ||
| + | console.log(data); | ||
| + | }); | ||
| + | </ | ||
| + | |||
| + | <code javascript promise.js> | ||
| + | // 2. Promise | ||
| + | import { readFile } from ' | ||
| + | |||
| + | readFile(' | ||
| + | .then((data) => console.log(data)) | ||
| + | .catch((err) => console.error(err)); | ||
| + | </ | ||
| + | |||
| + | <code javascript async-await.js> | ||
| + | // 3. async/ | ||
| + | import { readFile } from ' | ||
| + | |||
| + | try { | ||
| + | const data = await readFile(' | ||
| + | console.log(data); | ||
| + | } catch (err) { | ||
| + | console.error(' | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | 要点: | ||
| + | |||
| + | * '' | ||
| + | * 并发要并行时用 '' | ||
| + | * 未捕获的 Promise 拒绝在较新版本会直接让进程退出,务必处理错误。 | ||
| + | |||
| + | ===== 6. 常用内置模块 ===== | ||
| + | |||
| + | ^ 模块 ^ 典型用途 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | 读文件示例: | ||
| + | |||
| + | <code javascript> | ||
| + | import { readFile, writeFile } from ' | ||
| + | import path from ' | ||
| + | |||
| + | const file = path.join(import.meta.dirname, | ||
| + | const json = JSON.parse(await readFile(file, | ||
| + | json.updatedAt = new Date().toISOString(); | ||
| + | await writeFile(file, | ||
| + | </ | ||
| + | |||
| + | ===== 7. 写一个原生 HTTP 服务 ===== | ||
| + | |||
| + | <code javascript server.js> | ||
| + | import http from ' | ||
| + | |||
| + | const server = http.createServer((req, | ||
| + | if (req.url === '/ | ||
| + | res.writeHead(200, | ||
| + | return res.end(JSON.stringify({ ok: true })); | ||
| + | } | ||
| + | |||
| + | res.writeHead(200, | ||
| + | res.end(' | ||
| + | }); | ||
| + | |||
| + | const port = process.env.PORT || 3000; | ||
| + | server.listen(port, | ||
| + | </ | ||
| + | |||
| + | <code bash> | ||
| + | node server.js | ||
| + | curl http:// | ||
| + | </ | ||
| + | |||
| + | ===== 8. 用 Express 快速搭接口 ===== | ||
| + | |||
| + | Express 是 Node.js 生态里最主流的 Web 框架,核心只有「路由 + 中间件」两件事。 | ||
| + | 完整教程见 **[[express|Express 教程]]**(安装与项目结构、路由与 Router 模块化、req/ | ||
| + | |||
| + | <code bash> | ||
| + | npm install express | ||
| + | </ | ||
| + | |||
| + | <code javascript app.js> | ||
| + | import express from ' | ||
| + | |||
| + | const app = express(); | ||
| + | app.use(express.json()); | ||
| + | |||
| + | app.get('/ | ||
| + | res.json({ id: req.params.id, | ||
| + | }); | ||
| + | |||
| + | app.post('/ | ||
| + | res.status(201).json({ created: req.body }); | ||
| + | }); | ||
| + | |||
| + | // 统一错误处理:四个参数才会被识别为错误中间件 | ||
| + | app.use((err, | ||
| + | console.error(err); | ||
| + | res.status(500).json({ error: ' | ||
| + | }); | ||
| + | |||
| + | app.listen(3000, | ||
| + | </ | ||
| + | |||
| + | 同类替代:'' | ||
| + | |||
| + | ===== 9. 事件循环与性能要点 ===== | ||
| + | |||
| + | * **不要阻塞事件循环**:同步 API('' | ||
| + | * 定时器、I/ | ||
| + | * CPU 密集任务用 '' | ||
| + | * 大文件用 '' | ||
| + | * 内存泄漏排查:'' | ||
| + | |||
| + | ===== 10. 环境变量与配置 ===== | ||
| + | |||
| + | <code bash> | ||
| + | npm install dotenv | ||
| + | </ | ||
| + | |||
| + | <code javascript> | ||
| + | import ' | ||
| + | |||
| + | const db = process.env.DATABASE_URL; | ||
| + | </ | ||
| + | |||
| + | * '' | ||
| + | * 配置校验缺失的必填变量,启动即报错,别等到运行时才炸。 | ||
| + | * 生产环境通常由平台/ | ||
| + | |||
| + | ===== 11. 开发体验:watch 与 test ===== | ||
| + | |||
| + | <code bash> | ||
| + | node --watch app.js | ||
| + | node --test | ||
| + | </ | ||
| + | |||
| + | 调试相关的启动参数('' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | 内置测试示例: | ||
| + | |||
| + | <code javascript math.test.js> | ||
| + | import test from ' | ||
| + | import assert from ' | ||
| + | import { add } from ' | ||
| + | |||
| + | test(' | ||
| + | assert.equal(add(1, | ||
| + | }); | ||
| + | </ | ||
| + | |||
| + | ===== 12. Inspector:Node.js 的调试内核 ===== | ||
| + | |||
| + | ==== inspector 到底是什么? ==== | ||
| + | |||
| + | '' | ||
| + | |||
| + | * **V8 Inspector**:V8 引擎自带的调试器,能暂停 JS 执行、读变量、取调用栈; | ||
| + | * **'' | ||
| + | |||
| + | 所以一句话概括:**inspector 是 Node.js 与调试器之间的标准接口**。它和 Node.js 的关系可以这么看: | ||
| + | |||
| + | | 类比 | 浏览器 | Node.js | | ||
| + | | 运行时 | Chrome 渲染进程 | '' | ||
| + | | 调试内核 | V8 Inspector | 同一个 V8 Inspector | | ||
| + | | 对外协议 | CDP | CDP(一样) | | ||
| + | | 调试界面 | Chrome DevTools | Chrome DevTools / VS Code / '' | ||
| + | |||
| + | 正因为**用的是同一套协议和设备面板**,你在浏览器里怎么打断点,在 Node.js 里就怎么打。这也是为什么 Node.js 不需要额外安装调试插件——'' | ||
| + | |||
| + | 注意区分两个容易混淆的东西: | ||
| + | |||
| + | * '' | ||
| + | * '' | ||
| + | |||
| + | ==== 四种常见的调试方式 ==== | ||
| + | |||
| + | ===== 方式一:Chrome / Edge DevTools(最直观) ===== | ||
| + | |||
| + | <code bash> | ||
| + | node --inspect app.js | ||
| + | # Debugger listening on ws:// | ||
| + | </ | ||
| + | |||
| + | 然后在 Chrome 地址栏打开 '' | ||
| + | |||
| + | - 在 **Configure** 里确认有 '' | ||
| + | - 在 **Remote Target** 列表里点 **inspect**,或点 **Open dedicated DevTools for Node**。 | ||
| + | |||
| + | 之后就是熟悉的 Sources(断点)、Console、Call Stack、Scope、Performance(CPU Profile)、Memory(堆快照)。 | ||
| + | |||
| + | ===== 方式二:VS Code 附加调试 ===== | ||
| + | |||
| + | 在 '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | ] | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | 也可以不用 attach,直接 launch:''" | ||
| + | |||
| + | ===== 方式三:内置 CLI 调试器 node inspect ===== | ||
| + | |||
| + | 不装任何东西,在终端里断点调试: | ||
| + | |||
| + | <code bash> | ||
| + | node inspect app.js | ||
| + | </ | ||
| + | |||
| + | <code text> | ||
| + | break app.js: | ||
| + | cont # 继续执行 c | ||
| + | next # 单步跳过 n | ||
| + | step # 单步进入 s | ||
| + | out # 跳出 | ||
| + | repl # 进入交互式求值,打印变量 | ||
| + | exec(' | ||
| + | bt # 打印调用栈 | ||
| + | restart | ||
| + | </ | ||
| + | |||
| + | 适合服务器上没有图形界面、或者用 SSH 连进去排查的场景。 | ||
| + | |||
| + | ===== 方式四:代码里编程式使用 node: | ||
| + | |||
| + | <code javascript inspect-open.js> | ||
| + | import inspector from ' | ||
| + | |||
| + | // 在代码里打开调试端口(相当于运行时的 --inspect) | ||
| + | inspector.open(9229, | ||
| + | console.log(' | ||
| + | |||
| + | // 建一个会话,直接对进程求值 —— 可以做诊断脚本 | ||
| + | const session = new inspector.Session(); | ||
| + | session.connect(); | ||
| + | session.post(' | ||
| + | { expression: ' | ||
| + | (err, res) => { | ||
| + | if (err) return console.error(err); | ||
| + | console.log(res.result); | ||
| + | session.disconnect(); | ||
| + | }); | ||
| + | </ | ||
| + | |||
| + | 这条路径的价值不在日常打断点,而在于**做自诊断与自动化采集**:例如暴露一个 ''/ | ||
| + | |||
| + | ==== 参数与常用配置 ==== | ||
| + | |||
| + | ^ 参数 ^ 作用 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | 运行时给已经跑着的进程开 inspector(Linux/ | ||
| + | |||
| + | <code bash> | ||
| + | kill -USR1 < | ||
| + | </ | ||
| + | |||
| + | 注意:这样打开的 inspector **无法再关闭**,且 9229 端口只监听本机。 | ||
| + | |||
| + | ==== 安全提示 ==== | ||
| + | |||
| + | * 调试端口等同于**任意代码执行**入口,绝不要暴露到公网。 | ||
| + | * 远程排障用 SSH 端口转发,而不是 '' | ||
| + | <code bash> | ||
| + | # 先在本机执行,转发远端 9229 到本地 9229 | ||
| + | ssh -L 9229: | ||
| + | # 服务器上 | ||
| + | node --inspect app.js | ||
| + | </ | ||
| + | * 生产环境默认不要开 inspector;需要排障时临时开、排完关。 | ||
| + | |||
| + | ==== 调试之外:inspector 撑起来的一整套诊断能力 ==== | ||
| + | |||
| + | 理解 inspector 之后,很多看起来独立的工具都是它的延伸: | ||
| + | |||
| + | * **内存泄漏**:DevTools → Memory → Heap snapshot,对比两次快照看谁在增长; | ||
| + | * **CPU 热点**:DevTools → Performance 录制,或 '' | ||
| + | * **诊断报告**:'' | ||
| + | * **异步调用栈**:DevTools 里开启 async stack,看清 Promise 链从哪来。 | ||
| + | |||
| + | ===== 13. 常见坑 ===== | ||
| + | |||
| + | * '' | ||
| + | * 忘记 '' | ||
| + | * '' | ||
| + | * 相对路径依赖启动目录:用 '' | ||
| + | * 端口占用 '' | ||
| + | * 依赖体积失控:能用内置能力('' | ||
| + | * '' | ||
| + | * '' | ||
| + | * 在 '' | ||
| + | |||
| + | ===== 14. 进阶方向 ===== | ||
| + | |||
| + | * **TypeScript + Node**:'' | ||
| + | * **流与管道**:'' | ||
| + | * **实时通信**:'' | ||
| + | * **数据层**:'' | ||
| + | * **部署**:Docker 多阶段构建、PM2 进程守护、健康检查与优雅退出('' | ||
| + | * **可观测性**:结构化日志('' | ||
| + | |||
| + | ===== 小结 ===== | ||
| + | |||
| + | 学习路径建议:**异步 → 模块与 npm → http/fs 内置模块 → 框架写接口 → 调试(inspector)→ 工程化(测试、日志、部署)**。 | ||
| + | 先把事件循环和 async/await 吃透,剩下的都是在这两者之上的工程实践。 | ||
| + | |||
| + | ```mdk height=560 color=# | ||
| + | # Node.js | ||
| + | ## 运行时基础 | ||
| + | ### V8 引擎 + 单线程 + 事件循环 | ||
| + | ### 非阻塞 I/ | ||
| + | ### 安装 LTS / nvm / fnm | ||
| + | ## 模块系统 | ||
| + | ### CommonJS:require / module.exports | ||
| + | ### ESM:import / export(推荐) | ||
| + | ### 内置模块加 node: 前缀 | ||
| + | ## npm 生态 | ||
| + | ### package.json:type / scripts / exports | ||
| + | ### dependencies vs devDependencies | ||
| + | ### lock 文件要提交 | ||
| + | ### npx 直接运行命令 | ||
| + | ## 异步编程 | ||
| + | ### 回调 → Promise → async/ | ||
| + | ### 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:// | ||
| + | ### node: | ||
| + | ### 已有进程:kill -USR1 < | ||
| + | ### 安全:只绑 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 不暂停导致断点打不上 | ||
| + | ### 依赖膨胀 | ||
| + | ``` | ||