文档›迁移

从 Node.js 迁移

在保留 package.json 与 npm 依赖的前提下渐进迁移到 Deno 2

查看 Markdown 上游来源

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

分阶段采用

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

兼容约定

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 的行为差异。

官方参考：Node compatibility、Migrate to Deno。