# Node API 替换表

Deno 支持大量 `node:` API，所以迁移不等于把每个调用都重写。先用兼容 API 跑通，再在能减少依赖或改善可移植性时采用 Web/Deno API。

| Node.js | Deno / Web API | 建议 |
| --- | --- | --- |
| `fs.promises.readFile(path, "utf8")` | `Deno.readTextFile(path)` | 两者都需要文件权限 |
| `fs.promises.writeFile` | `Deno.writeTextFile` | 收紧到具体目录 |
| `http.createServer` | `Deno.serve` | 新 HTTP 服务首选 Web Request/Response |
| `process.env.NAME` | `Deno.env.get("NAME")` | 只授权指定变量 |
| `process.argv.slice(2)` | `Deno.args` | CLI 参数可直接迁移 |
| `child_process.spawn` | `new Deno.Command()` | 需要 `--allow-run=<cmd>` |
| `__dirname` | `new URL(".", import.meta.url)` | 保持 URL 语义，必要时转路径 |
| `crypto.randomUUID()` | `crypto.randomUUID()` | Web API 可直接复用 |
| `Buffer` | `Uint8Array` / `TextEncoder` | 协议边界优先 Web 类型 |

## 一个文件读取示例

```ts
// 兼容优先：保留 Node API
import { readFile } from "node:fs/promises";
const a = await readFile("config.json", "utf8");

// Deno-first：更短的文本 API
const b = await Deno.readTextFile("config.json");
```

两种代码都应以同样的最小权限运行：

```bash
deno run --allow-read=config.json main.ts
```

迁移测试至少覆盖路径、编码、stream/backpressure、信号、超时与错误类型；函数名相似不代表边界行为完全相同。

官方参考：[Node APIs](https://docs.deno.com/api/node/)、[Deno APIs](https://docs.deno.com/api/deno/)、[Web APIs](https://docs.deno.com/api/web/)。