migrate-to-deno

迁移到 Deno

需要 Deno 2.9 或更高版本。迁移后如需了解 Deno 的常规用法，请参阅 deno 技能。

大多数 Node 项目已经可以在 Deno 下运行

Deno 会读取现有的 package.json，解析相同的 npm 包，写入真正的 node_modules，运行相同的脚本，并支持 node: 内置模块。 TypeScript 无需构建即可运行。

通常无需更改代码——只需选择调用哪个二进制文件。不要一开始就重写导入，将依赖换成 Deno 专用依赖，或重组目录。提出这些做法是最常见的出错原因。

分阶段迁移

每个阶段都可独立使用，也可撤销。可根据项目情况选择停止在哪一阶段；许多团队会停在第 1 阶段。

第 1 阶段 — 仅将 Deno 用作包管理器

deno install

读取 package.json，解析相同的依赖，写入 node_modules，并创建 deno.lock——从任何现有的 package-lock.json、yarn.lock、 bun.lock 或 pnpm 锁文件初始化，因此固定版本和完整性哈希会原样保留，而不会发生变化。

应用仍在 node 下运行；团队成员不受影响。验证无误后提交 deno.lock。**如需回退：**删除 deno.lock 和 node_modules，然后运行 npm install。

第 2 阶段 — 使用 Deno 运行

deno run -A main.js      # or: deno -A main.js
deno task build          # runs scripts.build from package.json

此处使用 -A。目标是确认程序能正常运行，而不是设计权限策略——同时更改两者会让故障原因难以判断。

第 3 阶段 — 收紧权限

将 -A 换成能正常运行的最小权限集合：运行程序，查看它请求的权限，然后只授予所需权限。

deno run --allow-net=api.example.com --allow-read=./config --allow-env=PORT main.js

这是 Node 无法提供的能力，值得在部署前完成。

第 4 阶段 — 可选，采用内置工具链

使用 deno fmt 替代 prettier，deno lint 替代 eslint，deno test 替代 jest 或 vitest， deno check 替代 tsc，deno watch 替代 nodemon，deno compile 替代 pkg。

**这是可选的，对于现有项目通常不值得采用。**这些工具不能直接替换现有工具；功能尚未完全对等，因此这是真正的迁移，而非配置变更。已经在使用 prettier、eslint 和 vitest 且运行良好的项目，应继续使用它们，只将 Deno 用作运行时和包管理器。新项目优先使用内置工具。如果要迁移现有项目，请一次迁移一个工具。

命令对应关系

任务	npm	Yarn	pnpm	Bun	Deno
安装全部依赖	npm install	yarn install	pnpm install	bun install	deno install
添加依赖	npm i <p>	yarn add <p>	pnpm add <p>	bun add <p>	deno add <p>
添加开发依赖	npm i -D <p>	yarn add -D <p>	pnpm add -D <p>	bun add -d <p>	deno add -D <p>
移除依赖	npm uninstall <p>	yarn remove <p>	pnpm remove <p>	bun remove <p>	deno remove <p>
CI 安装	npm ci	yarn install --immutable†	pnpm i --frozen-lockfile	bun install --frozen-lockfile	deno ci
运行脚本	npm run <s>	yarn <s>	pnpm <s>	bun run <s>	deno task <s>
运行二进制文件	npx <p>	yarn dlx <p>	pnpm dlx <p>	bunx <p>	dx <p>
检查过期依赖	npm outdated	yarn outdated‡	pnpm outdated	bun outdated	deno outdated
安全审计	npm audit	yarn npm audit†	pnpm audit	bun audit	deno audit
查看依赖原因	npm ls <p>	yarn why <p>	pnpm why <p>	bun why <p>	deno why <p>
运行文件	node f.js			bun f.ts	deno f.ts
运行 TS	ts-node f.ts			bun f.ts	deno f.ts
监视	nodemon f.js			bun --watch f.ts	deno watch f.ts
格式化	prettier			prettier	deno fmt
代码检查	eslint				deno lint
测试	jest, vitest			bun test	deno test
覆盖率	nyc, c8				deno coverage
类型检查	tsc --noEmit			tsc	deno check
打包为二进制文件	pkg, nexe			bun build --compile	deno compile

† Yarn Berry（v2+）的写法。Yarn Classic（v1）使用 yarn install --frozen-lockfile 和 yarn audit。

‡ 仅适用于 Yarn Classic——Berry 已移除 yarn outdated。

dx 是随 Deno 一起安装的独立二进制文件，也是 deno x 的别名。 它不会出现在顶层 deno --help 输出中。和 npx 一样，它会在禁用沙盒的情况下运行软件包。

真正会导致问题的四件事

Requires net access to "..."（或 read、env、run）

Deno 默认不授予任何权限。添加所需的特定权限，或者使用 -A，同时先确认程序本身能够正常运行。

ReferenceError: require is not defined

包含 CommonJS 的文件正被解析为 ESM。.cjs 始终是 CommonJS，.mjs 始终是 ESM；.js 和 .ts 则遵循最近的 package.json 中的 "type"。对于 CommonJS 项目，请设置 "type": "commonjs"。

依赖损坏，或 postinstall 从未运行

默认情况下不会运行生命周期脚本。原生扩展会立即发现这一问题。批准记录在配置文件中，因此只需操作一次：

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3   # or name them directly

工具无法在 node_modules 中找到文件

Deno 使用 pnpm 风格的布局：实际文件位于 node_modules/.deno/ 中，并通过符号链接暴露。假设采用 npm 扁平提升目录树的工具需要：

{ "nodeModulesLinker": "hoisted" }

Deno 不支持的功能

请如实说明，而不要临时拼凑一个无法长久奏效的变通方案：

• Yarn Plug'n'Play。 Deno 会创建实际的 node_modules；.pnp.cjs 不会被使用，.yarnrc.yml 中的解析器设置也无法迁移。
• yarn patch / pnpm 修补过的依赖。 请将其纳入项目或进行分叉。
• overrides / resolutions。 请改用导入映射条目固定版本。
• .npmrc / .yarnrc.yml 中的注册表和解析器调整。
• Bun 构建功能——宏、HTMLRewriter、HTML 入口点。

各工具的详细信息

• references/FROM_NPM.md — 锁文件初始化、node_modules 布局、覆盖项
• references/FROM_YARN.md — Plug'n'Play、Berry 与 Classic、工作区
• references/FROM_PNPM.md — pnpm-workspace.yaml、catalog:、补丁
• references/FROM_BUN.md — Bun API 转换、bunfig.toml
• references/NODE_APIS.md — node: 内置模块、DENO_COMPAT、CJS/ESM

延伸阅读

• https://docs.deno.com/runtime/migrate/ — 官方迁移指南
• https://docs.deno.com/runtime/fundamentals/node/ — Node 和 npm 兼容性
• https://docs.deno.com/runtime/reference/node_apis/ — 各 Node API 模块的支持状态