显示页面讨论过去修订反向链接回到顶部 本页面只读。您可以查看源文件,但不能更改它。如果您觉得这是系统错误,请联系管理员。 ====== Node.js 教程 ====== Node.js 是基于 Chrome V8 引擎的 JavaScript **运行时**,让 JS 可以脱离浏览器在服务端运行。 它的核心特征是 **单线程 + 事件循环 + 非阻塞 I/O**:不适合做重 CPU 计算,但非常擅长 I/O 密集型场景(Web API、命令行工具、网关、实时通信、构建脚本)。 ===== 1. 环境准备 ===== * 安装:到 [[https://nodejs.org|nodejs.org]] 下载 **LTS** 版本,生产环境优先用 LTS。 * 版本管理(推荐):''nvm''(macOS/Linux)、''fnm'' 或 ''nvm-windows'',方便多版本切换。 * ''npx'' 随 npm 一起安装,可以直接运行包内命令,不用全局安装。 验证安装: <code bash> node -v npm -v </code> ===== 2. 第一个程序 ===== <code javascript hello.js> const name = process.argv[2] || 'world'; console.log(`hello, ${name}`); console.log('Node 版本:', process.version); </code> 运行: <code bash> node hello.js 小明 </code> 要点:''process'' 是全局对象;''process.argv'' 是命令行参数数组,前两项分别是 node 可执行文件路径和脚本路径,真正的参数从下标 2 开始。 ===== 3. 模块系统 ===== Node.js 有两套模块体系,新项目建议直接用 ESM。 ==== CommonJS(CJS,传统方式) ==== <code javascript math.js> function add(a, b) { return a + b; } module.exports = { add }; </code> <code javascript main.js> const { add } = require('./math.js'); console.log(add(1, 2)); </code> ==== ES Modules(ESM,推荐) ==== 在 ''package.json'' 里加 ''"type": "module"'',或把文件后缀写成 ''.mjs'': <code javascript math.mjs> export function add(a, b) { return a + b; } </code> <code javascript main.mjs> import { add } from './math.mjs'; console.log(add(1, 2)); </code> 注意几点: * ESM 中 ''__dirname'' / ''__filename'' 不存在,用 ''import.meta.dirname'' / ''import.meta.url'' 代替。 * ESM 的 ''import'' 会被提升,且必须在顶层;需要动态导入用 ''await import()''。 * 同一个项目里 CJS 和 ESM 可以互操作,但 CJS 里不能直接 ''require'' 纯 ESM 模块(新版可用 ''require(esm)'',需注意版本兼容)。 ===== 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 环境用) </code> ''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 的关键。三种写法按演进顺序: <code javascript callback.js> // 1. 回调(老写法,容易回调地狱) fs.readFile('a.txt', 'utf8', (err, data) => { if (err) return console.error(err); console.log(data); }); </code> <code javascript promise.js> // 2. Promise import { readFile } from 'node:fs/promises'; readFile('a.txt', 'utf8') .then((data) => console.log(data)) .catch((err) => console.error(err)); </code> <code javascript 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); } </code> 要点: * ''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'' | 调起子进程执行命令 | 读文件示例: <code javascript> 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'); </code> ===== 7. 写一个原生 HTTP 服务 ===== <code javascript 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}`)); </code> <code bash> node server.js curl http://localhost:3000/health </code> ===== 8. 用 Express 快速搭接口 ===== Express 是 Node.js 生态里最主流的 Web 框架,核心只有「路由 + 中间件」两件事。 完整教程见 **[[express|Express 教程]]**(安装与项目结构、路由与 Router 模块化、req/res、中间件洋葱模型、统一错误处理、zod 校验、JWT 认证、multer 上传、supertest 测试、生产部署、Express 5 变化)。下面先给一个最小可跑示例。 <code bash> npm install express </code> <code javascript 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')); </code> 同类替代:''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(原理与用法见第 12 节 Inspector)。 ===== 10. 环境变量与配置 ===== <code bash> npm install dotenv </code> <code javascript> import 'dotenv/config'; const db = process.env.DATABASE_URL; </code> * ''.env'' **不要提交**,把模板写进 ''.env.example''。 * 配置校验缺失的必填变量,启动即报错,别等到运行时才炸。 * 生产环境通常由平台/容器注入环境变量,不一定用 ''dotenv''。 ===== 11. 开发体验:watch 与 test ===== <code bash> node --watch app.js # 文件变更自动重启(Node 18.11+) node --test # 运行 node:test 测试 </code> 调试相关的启动参数(''--inspect''、断点、DevTools)单独放在下一节详解。 <code json> { "scripts": { "dev": "node --watch app.js", "start": "node app.js", "test": "node --test" } } </code> 内置测试示例: <code javascript 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); }); </code> ===== 12. Inspector:Node.js 的调试内核 ===== ==== inspector 到底是什么? ==== ''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 的模块**,作用是“在程序内部编程式地开启会话、执行表达式”。 ==== 四种常见的调试方式 ==== ===== 方式一:Chrome / Edge DevTools(最直观) ===== <code bash> node --inspect app.js # Debugger listening on ws://127.0.0.1:9229/xxxxxxxx-... </code> 然后在 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(堆快照)。 ===== 方式二:VS Code 附加调试 ===== 在 ''.vscode/launch.json'' 里加 attach 配置,然后 F5 选择该配置: <code json> { "version": "0.2.0", "configurations": [ { "type": "node", "request": "attach", "name": "Attach to Node", "port": 9229, "restart": true } ] } </code> 也可以不用 attach,直接 launch:''"request": "launch"''、''"program": "${workspaceFolder}/app.js"'',IDE 会自动加上 ''--inspect''。 ===== 方式三:内置 CLI 调试器 node inspect ===== 不装任何东西,在终端里断点调试: <code bash> node inspect app.js </code> <code text> break app.js:12 # 或简写 sb(12) 在下一行断点 cont # 继续执行 c next # 单步跳过 n step # 单步进入 s out # 跳出 repl # 进入交互式求值,打印变量 exec('user.name') # 直接求值 bt # 打印调用栈 restart # 重启 </code> 适合服务器上没有图形界面、或者用 SSH 连进去排查的场景。 ===== 方式四:代码里编程式使用 node:inspector ===== <code javascript 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(); }); </code> 这条路径的价值不在日常打断点,而在于**做自诊断与自动化采集**:例如暴露一个 ''/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): <code bash> kill -USR1 <pid> # 进程会打印 ws://127.0.0.1:9229/... </code> 注意:这样打开的 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 撑起来的一整套诊断能力 ==== 理解 inspector 之后,很多看起来独立的工具都是它的延伸: * **内存泄漏**:DevTools → Memory → Heap snapshot,对比两次快照看谁在增长; * **CPU 热点**:DevTools → Performance 录制,或 ''node --cpu-prof''; * **诊断报告**:''process.report.writeReport()'' 或 ''node --report-on-signal'' 导出 JSON(含堆栈、系统信息、libuv 句柄),进程卡死后很有用; * **异步调用栈**:DevTools 里开启 async stack,看清 Promise 链从哪来。 ===== 13. 常见坑 ===== * ''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 不暂停导致断点打不上 ### 依赖膨胀 ``` 登录 Detach Close 该主题尚不存在 您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。 nodejs.txt 最后更改: 2026/11/10 17:14由 张叶安 登录