# 从 Node.js 迁移到 Deno

Deno 2 能读取 `package.json`、解析 npm 包并运行大量 Node API。迁移的正确起点不是重写 imports，而是证明现有应用在另一 runtime 下仍然满足测试与生产约束。

## 四段路线

<Cards>
  <Card title="1. 建立兼容基线" description="固定版本，保留现有安装方式，先运行无副作用脚本与测试。" href="/docs/migration/from-node" />
  <Card title="2. 对齐包与配置" description="理解 package.json、deno.json、lockfile 和 node_modules 模式。" href="/docs/migration/packages-and-config" />
  <Card title="3. 逐个替换 API" description="保留可工作的 node: API，只在有收益时采用 Web/Deno API。" href="/docs/migration/api-mapping" />
  <Card title="4. 清理兼容问题" description="处理 CommonJS、原生扩展、install scripts、权限和测试差异。" href="/docs/migration/troubleshooting" />
</Cards>

## 每阶段验收

```bash
deno install
deno check src/main.ts
deno test
deno task start
```

在 CI、开发机和目标生产环境都通过之前，不删除旧 lockfile、旧 runtime 命令或部署路径。一次提交只改变运行时、包管理、测试、框架或部署中的一层。

<Callout type="info" title="何时暂缓迁移">
关键依赖只有未兼容的 Node-API 二进制、系统深度依赖自定义 loader，或团队没有生产回归测试时，先补证据和隔离层；不要为了“完成迁移”重写稳定业务。
</Callout>

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