第 7 章：工程化与部署

代码写完只是开始。这一章讲 Node 服务怎么调试、怎么压性能、怎么用 pm2 和 Docker 稳定上线。

---

7.1 调试

方式一：console.log（最常用，但别滥用）

简单直接，适合快速定位，但生产代码要清理干净。

方式二：Node 内置调试器

用 --inspect 启动，配合 Chrome DevTools 断点调试：

node --inspect index.js
# 输出 Debugger listening on ws://... ，打开 Chrome 的 chrome://inspect 连接

方式三：node --watch 热重载

开发时改代码自动重启（替代 nodemon）：

node --watch index.js

实用建议：日常开发 --watch + console.log 就够；遇到难查的逻辑 bug 再用 --inspect 断点。

---

7.2 性能优化要点

Node 性能问题多数是这几种，逐一排查：

问题	表现	对策
阻塞主线程	请求变慢、整体卡顿	找 CPU 密集代码，移出主线程（worker_threads）或改异步
同步 API 滥用	高并发下雪崩	readFileSync 等同步方法只用于启动阶段
串行 await	慢	独立任务用 Promise.all 并行
无缓存	重复计算/查询	加内存缓存（如 Map、Redis）
未设超时	一个慢请求拖垮服务	所有外部调用设超时（AbortController）

快速定位：用 --prof 做 CPU profile，或用 APM 工具（如 clinic.js）可视化瓶颈。

---

7.3 pm2：进程守护

Node 是单进程，一旦崩溃整个服务就挂了。pm2 是 Node 最常用的进程管理器，负责守护、多实例、日志：

npm install -g pm2

pm2 start index.js --name my-app   # 启动
pm2 list                           # 查看所有进程
pm2 logs my-app                    # 看日志
pm2 restart my-app                 # 重启
pm2 stop my-app                    # 停止
pm2 save                           # 保存进程列表（配合 pm2 startup 开机自启）

cluster 模式：Node 单线程只能用一个 CPU 核，pm2 的 cluster 模式能按核数起多个实例，充分利用多核：

pm2 start index.js -i max   # 按 CPU 核数启动多个实例

        ┌──────────────┐
用户 ──►│  负载均衡     │──► worker 1（核 1）
        │ (cluster模式) │──► worker 2（核 2）
        └──────────────┘──► worker 3（核 3）

注意：cluster 模式要求你的应用无状态（session 等状态要放 Redis），否则多实例间状态不同步。

---

7.4 Docker 部署

把 Node 服务容器化，一次构建到处运行。一个标准的 Node Dockerfile：

# 构建阶段
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build

# 运行阶段（只带产物，镜像更小）
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --production
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

多阶段构建的好处：构建依赖（devDependencies）不进入最终镜像，镜像体积小、更安全。

配合 docker-compose 起整套服务：

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    restart: unless-stopped

┌─────────────────────────────────────────┐
│  Docker 容器                             │
│  ┌─────────────┐   ┌─────────────┐      │
│  │  Node 服务   │◄──│  Nginx 反代  │◄── 外部流量
│  └─────────────┘   └─────────────┘      │
│  （多实例/pm2/直接 node）                  │
└─────────────────────────────────────────┘

实践建议：小项目直接 pm2 裸机部署即可；要迁移、隔离、多环境，用 Docker；上 K8s 是流量很大之后的事，别过早引入复杂度。

---

7.5 上线检查清单

部署前逐项核对：

• [ ] 环境变量（API Key、数据库连接）用 process.env，不硬编码、不进 git
• [ ] 所有外部调用设了超时
• [ ] 错误处理完整，uncaughtException / unhandledRejection 有兜底日志
• [ ] 日志有统一格式，便于排查
• [ ] 敏感接口有鉴权
• [ ] 健康检查接口（/health）供监控探活
• [ ] 用 pm2/Docker 保证崩溃自动拉起

---

7.6 全书小结

回顾整本 Node.js 学习笔记：

第1章 运行机制  ──► 单线程异步、事件循环（地基）
第2章 模块系统  ──► CommonJS/ESM、npm（组织代码）
第3章 异步编程  ──► Promise/async/await（核心能力）
第4章 核心模块  ──► fs/path/http/stream（武器库）
第5章 HTTP服务  ──► Express、中间件洋葱模型（写服务）
第6章 对接大模型 ──► SSE 流式、工程封装（AI 实战）
第7章 工程部署  ──► 调试、性能、pm2、Docker（上线）

学习建议：掌握第 1~3 章的「异步 + 事件循环」就理解了 Node 的魂；第 6 章的「流式对接大模型」是 AI 时代最值得练的实战。其余按需查阅即可。