nodejs

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录 前一修订版
后一修订版
前一修订版
nodejs [2026/10/17 12:14] – 创建 Node.js 教程主页面 张叶安nodejs [2026/11/10 17:14] (当前版本) – 思维导图扩充 Express 子节点 张叶安
行 190: 行 190:
  
 ===== 8. 用 Express 快速搭接口 ===== ===== 8. 用 Express 快速搭接口 =====
 +
 +Express 是 Node.js 生态里最主流的 Web 框架,核心只有「路由 + 中间件」两件事。
 +完整教程见 **[[express|Express 教程]]**(安装与项目结构、路由与 Router 模块化、req/res、中间件洋葱模型、统一错误处理、zod 校验、JWT 认证、multer 上传、supertest 测试、生产部署、Express 5 变化)。下面先给一个最小可跑示例。
  
 <code bash> <code bash>
行 226: 行 229:
   * CPU 密集任务用 ''worker_threads'' 或多进程(''cluster''、PM2)分摊。   * CPU 密集任务用 ''worker_threads'' 或多进程(''cluster''、PM2)分摊。
   * 大文件用 ''stream'' + ''pipeline'',避免一次性读进内存。   * 大文件用 ''stream'' + ''pipeline'',避免一次性读进内存。
-  * 内存泄漏排查:''node --inspect'' + Chrome DevTools 的 Memory / Heap snapshot。+  * 内存泄漏排查:''node --inspect'' + Chrome DevTools 的 Memory / Heap snapshot(原理与用法见第 12 节 Inspector)。
  
 ===== 10. 环境变量与配置 ===== ===== 10. 环境变量与配置 =====
行 244: 行 247:
   * 生产环境通常由平台/容器注入环境变量,不一定用 ''dotenv''。   * 生产环境通常由平台/容器注入环境变量,不一定用 ''dotenv''。
  
-===== 11. 调试与开发体验 =====+===== 11. 开发体验:watch 与 test =====
  
 <code bash> <code bash>
 node --watch app.js        # 文件变更自动重启(Node 18.11+) node --watch app.js        # 文件变更自动重启(Node 18.11+)
-node --inspect app.js      # 打开调试协议,浏览器 chrome://inspect 连接 
 node --test                # 运行 node:test 测试 node --test                # 运行 node:test 测试
 </code> </code>
 +
 +调试相关的启动参数(''--inspect''、断点、DevTools)单独放在下一节详解。
  
 <code json> <code json>
行 274: 行 278:
 </code> </code>
  
-===== 12. 常见坑 =====+===== 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:'' 前缀更清晰。   * ''require('fs')'' 写成 ''fs'' 没装包 → 内置模块要加 ''node:'' 前缀更清晰。
行 282: 行 432:
   * 端口占用 ''EADDRINUSE'':换端口或结束旧进程。   * 端口占用 ''EADDRINUSE'':换端口或结束旧进程。
   * 依赖体积失控:能用内置能力(''fetch''、''fs/promises''、''node:test'')就不加包。   * 依赖体积失控:能用内置能力(''fetch''、''fs/promises''、''node:test'')就不加包。
 +  * ''--inspect'' 时断点打不上:程序早就跑过去了,改用 ''--inspect-brk'' 从第一行停住。
 +  * ''EADDRINUSE: 9229'':上一个调试进程没退干净,先杀掉旧进程再启动。
 +  * 在 ''chrome://inspect'' 里看不到进程:检查地址是不是 ''localhost:9229''、端口是否被防火墙挡、以及是否用了 ''0.0.0.0'' 之外的绑定。
  
-===== 13. 进阶方向 =====+===== 14. 进阶方向 =====
  
   * **TypeScript + Node**:''tsx'' / ''ts-node'' 直接跑,生产先编译或用 Node 原生类型剥离。   * **TypeScript + Node**:''tsx'' / ''ts-node'' 直接跑,生产先编译或用 Node 原生类型剥离。
行 294: 行 447:
 ===== 小结 ===== ===== 小结 =====
  
-学习路径建议:**异步 → 模块与 npm → http/fs 内置模块 → 框架写接口 → 工程化(测试、日志、部署)**。+学习路径建议:**异步 → 模块与 npm → http/fs 内置模块 → 框架写接口 → 调试(inspector)→ 工程化(测试、日志、部署)**。
 先把事件循环和 async/await 吃透,剩下的都是在这两者之上的工程实践。 先把事件循环和 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.1792210453.txt.gz
  • 最后更改: 2026/10/17 12:14
  • 由 张叶安