# 从 Node.js 迁移

Deno 2 可以直接运行许多现有 Node 项目。迁移目标不是一次性改写全部 import，而是建立可回滚的兼容性证据。

## 分阶段采用

1. 固定 Deno 版本，在现有分支运行 `deno --version`。
2. 保留 `package.json`、当前 lockfile 和 `node_modules` 策略，先运行一个无副作用脚本。
3. 执行现有测试；记录失败的 Node API、原生扩展、loader 与生命周期脚本。
4. 引入 `deno.json` tasks，将 Deno 命令与原命令并行运行。
5. 只有 CI、开发机和生产验证都通过后，才删除旧工具或锁文件。

## 兼容约定

```ts
import { readFile } from "node:fs/promises";
import express from "npm:express";
```

Deno 也能根据 `package.json` 解析常见裸 npm 导入。是否启用/需要本地 `node_modules` 由项目配置和依赖行为决定，不要假定一种模式适合全部包。

## 高风险区域

- Node-API 原生扩展、postinstall 脚本与二进制下载；
- 自定义 ESM loader、模块解析 hack 与隐式扩展名；
- Jest/Vitest 全局、fake timers、snapshot 差异；
- 依赖未显式声明的环境变量、文件路径和网络访问；
- `process`、Buffer、streams 与边缘 Node API 的行为差异。

<Callout type="warn" title="一次只替换一层">
不要在同一个迁移提交里同时更换运行时、测试框架、包管理器、格式化规则和部署平台。否则失败时无法定位变量。
</Callout>

官方参考：[Node compatibility](https://docs.deno.com/runtime/fundamentals/node/)、[Migrate to Deno](https://docs.deno.com/runtime/migrate/)。