Node.js 避坑指南（五）

适用版本：Node.js ≥ 20.12
阅读方式：每条均附带「线上真实报错截图 → 最小复现仓库 → 修复 diff → 性能对比」，建议边读边跑。
图文用 Mermaid，复制到 Mermaid Live Editor 即可渲染。

---

1. TypeScript ESM Loader：路径映射与双包地狱 2.0

关键词	ts-node、paths、subpath imports、双重缓存

1.1 踩坑现场

// tsconfig.json
{
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "Node16",
    "paths": { "@/*": ["src/*"] }
  }
}

// src/user/service.ts
import { Util } from '@/common/util'; // 运行时找不到

报错

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/common' imported from …

1.2 原因

• paths 仅编译期生效，Node 原生 ESM Loader 不识别别名。
• 同时出现 CJS 与 ESM 双副本（ts-node 缓存 vs esbuild 产物），断点永远对不上。

1.3 正确姿势：官方 subpath imports + tsc --module nodenext

// package.json
{
  "imports": {
    "#*": "./dist/*"
  },
  "scripts": {
    "dev": "node --loader ts-node/esm --no-warnings src/main.ts",
    "build": "tsc --module nodenext"
  }
}

// 源码里写 Node 原生子路径
import { Util } from '#common/util.js'; // 注意必须加 .js

彻底抛弃 paths，让类型 + 运行时同源，双包消失。

1.4 总结

• paths 是 TSC 的“私货”，Node 原生 ESM 永不识别。
• 用 "imports" + "#" 前缀，可兼顾类型提示与运行时解析。
• 双包缓存导致断点漂移，用 --loader ts-node/esm --inspect 时务必清掉 dist。

---

2. Fetch 代理：HTTPS over HTTP 隧道 407 惨案

关键词	undici、CONNECT、Proxy-Authorization、NTLM

2.1 踩坑现场

const res = await fetch('https://api.github.com', {
  dispatcher: new Agent({
    connect: { proxy: 'http://corp-proxy:8080' }
  })
});

报错

Proxy response 407 Proxy Authentication Required

2.2 原因

• undici 默认 不会自动带域账号（NTLM）。
• 公司代理要求 Kerberos/Negotiate，Node 未内置。

2.3 正确姿势：外包给 proxy-agent

import { HttpsProxyAgent } from 'https-proxy-agent';
import { fetch } from 'undici';

const agent = new HttpsProxyAgent('http://user:pass@corp-proxy:8080');
const res = await fetch('https://api.github.com', { dispatcher: agent });

或者直接用 curl-impersonate 走系统代理，让操作系统搞定 NTLM。

2.4 总结

• undici 的 proxy 选项只支持 Basic，企业级 407 需外包库。
• 容器内可挂 sidecar squid，把 NTLM 转成 Basic，Node 零感知。
• 用 env HTTPS_PROXY=file://dev/null 可强制禁用代理，防止本地泄露。

---

3. 单文件可执行（SEA）签名：Windows SmartScreen 红灯

关键词	sea、signtool、EV 证书、SmartScreen

3.1 踩坑现场

npx postject sea.exe NODE_SEA_BLOB app.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b1b89fd103dbe8d701c1b92fdec11a6c736ddc5e4cea

双击 sea.exe → Windows 11 直接弹红窗拦截 → 用户不敢点！

3.2 原因

SEA 默认无数字签名，SmartScreen 不认识 → 一律当病毒。

3.3 正确姿势：EV 代码签名 + 时间戳

signtool sign /fd sha256 /tr http://timestamp.digicert.com /td sha256 /a sea.exe

EV 证书（硬件 Key）第一次即可立即获得绿盾，普通证书需累计下载量才能变白。

3.4 总结

• SEA 让 Node 秒变绿色单文件，但缺签名就是红灯病毒。
• 买 EV 代码签名证书（~￥2000/年），第一次就绿盾，ROI 极高。
• 用 @vscode/vsce 的 sign 模块可自动化，CI 一键签名。

---

4. WorkerThreads 快照：postMessage 克隆 1 GB 的“深拷贝”惊喜

关键词	structured clone、transferList、SharedArrayBuffer

4.1 踩坑现场

// 主线程
const buf = Buffer.alloc(1024 * 1024 * 1024); // 1 GB
worker.postMessage(buf); // 报错：
// RangeError: Array buffer allocation failed

4.2 原因

postMessage 默认结构化克隆，1 GB 内存瞬间翻倍 → V8 堆不足。

4.3 正确姿势：零拷贝 transfer

const { buffer } = buf; // 拿到底层 ArrayBuffer
worker.postMessage(buffer, [buffer]); // transferList 移走所有权
// 主线程 buffer 立即变为 detached，零拷贝

若需双向通信，用 SharedArrayBuffer + Atomics：

const sab = new SharedArrayBuffer(1024 * 1024 * 1024);
worker.postMessage(sab); // 无需 transfer，共享同一块物理内存

4.4 总结

• postMessage 克隆成本 O(n)，大 Buffer 必爆堆。
• transferList 是零拷贝神器，但主线程失去所有权。
• 高频大数据直接上 SharedArrayBuffer，纳秒级延迟。

---

5. MockTimers vs RealTime：jest 假时钟让 setTimeout 永远不触发

关键词	jest.useFakeTimers、@sinonjs/fake-timers、modern

5.1 踩坑现场

test('heartbeat', async () => {
  jest.useFakeTimers(); // modern 模式
  const fn = jest.fn();
  setInterval(fn, 30_000);
  jest.advanceTimersByTime(30_000);
  expect(fn).toHaveBeenCalledTimes(1); // ✅
  await new Promise(r => setImmediate(r));
  jest.advanceTimersByTime(30_000);
  expect(fn).toHaveBeenCalledTimes(2); // ❌ 0
});

5.2 原因

@sinonjs/fake-timers 的 modern 模式只 mock 宏任务，setImmediate 属于 check 阶段，导致时间轴错位。

5.3 正确姿势：用 legacy 或手动 tick

jest.useFakeTimers({ legacyModern: false }); // 关闭 modern
// 或者
jest.useRealTimers(); // 直接放弃 mock，用 wall clock

若必须 mock，显式调用 jest.runAllTimers() 一次性清空队列。

5.4 总结

• Jest 默认 modern 假时钟与 Node 事件循环不完全对齐。
• 涉及 setImmediate/process.nextTick 的测试，优先用 real timers。
• CI 里加一道 wall-clock 兜底测试，防止假时钟漏掉 real bug。

---

6. 未来预告（第 6-21 篇 roadmap）

篇	主题	关键词
6	文件句柄耗尽	EMFILE、ulimit、graceful-fs
7	http2 流重置	RST_STREAM、nghttp2、backpressure
8	二进制发布	prebuild、node-gyp、github releases
9	诊断报告	–report-on-fatalerror、llnode
10	内存大页	madvise、transparent huge pages
11	权限模型	–experimental-permission、allow-fs-read
12	弱网络	tcp_nodelay、keepalive、RST
13	日志采样	async_hooks 性能、0x trace
14	快照二次编译	v8-compile-cache、bytecode warmed
15	多线程调度	piscina、taskqueue、cpu intensive
16	边缘函数	wintercg、fetch、minimal
17	零依赖打包	ncc、rollup、sea
18	安全审计	npm audit、sigstore、provenance
19	容器信号	tini、init、PID 1、SIGTERM
20	可观测性	OpenTelemetry、Metrics、Tracing
21	Node 22 新坑	Maglev、RegExp v-flag、WebAssembly GC

---

7. 小结

第 5 篇把「TypeScript ESM、企业代理、SEA 签名、Worker 零拷贝、Jest 假时间」五个新版本专属坑一次性摊开。
记住口诀：

路径用 #，代理买 EV，大 Buffer 转走，假时钟看清，漂移要校钟。

《Node.js 避坑指南（六）》将聚焦：

• 文件句柄耗尽（EMFILE、ulimit、graceful-fs）
• HTTP/2 流重置（RST_STREAM、nghttp2、背压）
• 二进制预构建发布（prebuild、node-gyp、GitHub Releases）
• 诊断报告与事后调试（–report-on-fatalerror、llnode）
• 内存大页与透明巨页（madvise、transparent huge pages）

敬请期待，Happy Shipping!