Node and npm Compatibility

• Deno 兼容 Node。大多数 Node 项目可以在 Deno 中运行，几乎不需要更改！

• Deno 支持 npm 包。只需在导入时使用 npm: 说明符，Deno 会处理其余部分。

例如，在 Deno 项目中，您可以这样从 npm 导入 Hono：

import { Hono } from "npm:hono";

这就是你开始所需了解的全部！但是，在这两个运行时之间有一些关键差异，你可以利用这些差异在将你的 Node.js 项目迁移到 Deno 时使代码更简单、更小。

使用 Node 的内置模块 Jump to heading#

Deno 提供了一个兼容层，允许在 Deno 程序中使用 Node.js 的内置 API。要使用它们，您需要在任何使用这些 API 的导入语句中添加 node: 前缀：

import * as os from "node:os";
console.log(os.cpus());

然后通过 deno run main.mjs 运行，您会注意到它与在 Node.js 中运行程序时输出相同。

更新您应用程序中的任何导入以使用 node: 前缀，应该能使任何使用 Node 内置 API 的代码照常工作。

为了方便更新现有代码，Deno 会为未使用 node: 前缀的导入提供有用的提示：

import * as os from "os";
console.log(os.cpus());

$ deno run main.mjs
error: Relative import path "os" not prefixed with / or ./ or ../
  hint: If you want to use a built-in Node module, add a "node:" prefix (ex. "node:os").
    at file:///main.mjs:1:21

相同的提示和其他快速修复也由 Deno LSP 在您的编辑器中提供。

探索内置的 Node API

使用 npm 包 Jump to heading#

Deno 原生支持通过使用 npm: 前缀导入 npm 包。例如：

import * as emoji from "npm:node-emoji";

console.log(emoji.emojify(`:sauropod: :heart:  npm`));

可以通过以下命令运行：

$ deno run main.js
🦕 ❤️ npm

在执行 deno run 命令之前，不需要 npm install，也无需创建 node_modules 文件夹。这些包同样受到与 Deno 中其他代码相同的权限约束。

npm 前缀的格式如下：

npm:[@][/]

有关流行库的示例，请参考 教程部分。

CommonJS 支持 Jump to heading#

CommonJS 是一种在ES 模块之前就存在的模块系统。尽管我们坚定地相信 ES 模块是 JavaScript 的未来，但依然存在数以百万计的使用 CommonJS 编写的 npm 库，而 Deno 提供了对它们的全面支持。Deno 将自动确定一个包是否使用 CommonJS，并在导入时无缝工作：

import react from "npm:react";
console.log(react);

$ deno run -E main.js
18.3.1

npm:react 是一个 CommonJS 包。Deno 允许您像导入 ES 模块一样导入它。

Deno 强烈建议在您的代码中使用 ES 模块，但也支持 CommonJS，具有以下限制：

在使用 CommonJS 模块时 Deno 的权限系统仍然有效。 可能需要提供至少 --allow-read 权限，因为 Deno 将探测文件系统中的 package.json 文件和 node_modules 目录，以正确解析 CommonJS 模块。

使用 .cjs 扩展名 Jump to heading#

如果文件扩展名为 .cjs，Deno 将把该模块视为 CommonJS。

const express = require("express");

Deno 不会查看 package.json 文件和 type 选项来判断文件是 CommonJS 还是 ESM。

在使用 CommonJS 时，Deno 期望依赖项将手动安装，并且将存在一个 node_modules 目录。最好在您的 deno.json 中设置 "nodeModulesDir": "auto" 以确保这一点。

$ cat deno.json
{
  "nodeModulesDir": "auto"
}

$ deno install npm:express
Add npm:express@5.0.0

$ deno run -R -E main.cjs
[Function: createApplication] {
  application: {
    init: [Function: init],
    defaultConfiguration: [Function: defaultConfiguration],
    ...
  }
}

-R 和 -E 标志用于允许权限读取文件和环境变量。

package.json type 选项 Jump to heading#

如果存在与该文件相邻的 package.json 文件，并且具有选项 "type": "commonjs"，Deno 将尝试将 .js、.jsx、.ts 和 .tsx 文件作为 CommonJS 加载。

{
  "type": "commonjs"
}

const express = require("express");

像 Next.js 的打包工具等工具将自动生成这样的 package.json 文件。

如果您有一个已存在的使用 CommonJS 模块的项目，可以通过向 package.json 文件添加 "type": "commonjs" 选项，使其与 Node.js 和 Deno 一起工作。

始终检测文件是否可能是 CommonJS Jump to heading#

通过在 Deno >= 2.1.2 中使用 --unstable-detect-cjs 运行，您可以告诉 Deno 分析模块是否可能是 CommonJS。除非存在一个带有 { "type": "module" } 的 package.json 文件，否则该设置将生效。

在文件系统中查找 package.json 文件并分析模块以检测它是否是 CommonJS 会比不这样做耗时。因此，为了避免使用 CommonJS，Deno 默认不执行此行为。

手动创建 require() Jump to heading#

替代的方法是手动创建 require() 函数的实例：

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const express = require("express");

在这种情况下，将适用与运行 .cjs 文件时相同的要求——需要手动安装依赖项并授予适当的权限标志。

require(ESM) Jump to heading#

Deno 的 require() 实现支持要求 ES 模块。

这与 Node.js 中的工作方式相同，您只能 require() 其模块图中没有顶级 await 的 ES 模块——或者换句话说，您只能 require() “同步”的 ES 模块。

export function greet(name) {
  return `Hello ${name}`;
}

import { greet } from "./greet.js";

export { greet };

const esm = require("./esm");
console.log(esm);
console.log(esm.greet("Deno"));

$ deno run -R main.cjs
[Module: null prototype] { greet: [Function: greet] }
Hello Deno

导入 CommonJS 模块 Jump to heading#

您还可以在 ES 模块中导入 CommonJS 文件。

module.exports = {
  hello: "world",
};

import greet from "./greet.js";
console.log(greet);

$ deno run main.js
{
  "hello": "world"
}

提示和建议

Deno 会提供有用的提示和建议，指导您在处理 CommonJS 模块时如何编写有效代码。

例如，如果您尝试运行没有 .cjs 扩展名的 CommonJS 模块，或没有带有 { "type": "commonjs" } 的 package.json，您可能会看到：

module.exports = {
  hello: "world",
};

$ deno run main.js
error: Uncaught (in promise) ReferenceError: module is not defined
module.exports = {
^
    at file:///main.js:1:1

    info: Deno supports CommonJS modules in .cjs files, or when the closest
          package.json has a "type": "commonjs" option.
    hint: Rewrite this module to ESM,
          or change the file extension to .cjs,
          or add package.json next to the file with "type": "commonjs" option,
          or pass --unstable-detect-cjs flag to detect CommonJS when loading.
    docs: https://docs.deno.com/go/commonjs

导入类型 Jump to heading#

许多 npm 包随附类型，您可以直接导入这些类型并使用它们：

import chalk from "npm:chalk@5";

一些包不随附类型，但您可以使用 @ts-types 指令指定它们的类型。例如，使用 @types 包：

// @ts-types="npm:@types/express@^4.17"
import express from "npm:express@^4.17";

模块解析

官方的 TypeScript 编译器 tsc 支持不同的 moduleResolution 设置。 Deno 仅支持现代的 node16 解析。不幸的是，许多 npm 包在 node16 模块解析下未能正确提供类型，可能会导致 deno check 报告类型错误，而 tsc 不报告这些错误。

如果 npm: 导入的默认导出似乎具有错误类型（正确的类型似乎在 .default 属性下），很可能是该包在从 ESM 的 node16 模块解析下提供了错误的类型。您可以通过检查是否在 tsc --module node16 和 package.json 中 "type": "module" 时也发生错误来验证这一点，或通过咨询 类型错误吗？ 网站（特别是在 “从 ESM 的 node16” 行）。

如果您想使用不支持 TypeScript node16 模块解析的包，您可以：

1. 在该包的问题跟踪器上打开一个问题报告。 （或许可以贡献一个修复 😃（但不幸的是，由于包需要支持 ESM 和 CJS 缺乏工具，默认导出需要不同的语法。参见 microsoft/TypeScript#54593）
2. 使用一个 CDN，该 CDN 为 Deno 支持重建包，而不是使用 npm: 标识。
3. 使用 // @ts-expect-error 或 // @ts-ignore 忽略您代码库中出现的类型错误。

包括 Node 类型 Jump to heading#

Node 随附许多内置类型，如 Buffer，这些类型可能在 npm 包的类型中引用。要加载这些类型，您必须向 @types/node 包添加类型引用指令：

/// <reference types="npm:@types/node" />

注意，在大多数情况下，不指定版本通常是可以的，因为 Deno 将尝试与其内部的 Node 代码保持同步，但如果必要，您可以始终覆盖使用的版本。

可执行的 npm 脚本 Jump to heading#

具有 bin 条目的 npm 包可通过以下格式的标识从命令行执行，而无需进行 npm install：

npm:[@][/]

例如：

$ deno run --allow-read npm:cowsay@1.5.0 "Hello there!"
 ______________
< Hello there! >
 --------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

$ deno run --allow-read npm:cowsay@1.5.0/cowthink "What to eat?"
 ______________
( What to eat? )
 --------------
        o   ^__^
         o  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

node_modules Jump to heading#

当您运行 npm install 时，npm 会在您的项目中创建一个 node_modules 目录，其中存放 package.json 文件中指定的依赖项。

Deno 使用 npm 指定符 将 npm 包解析到中心的全局 npm 缓存，而不是在您的项目中使用 node_modules 文件夹。这是理想的，因为它占用更少的空间，并保持您的项目目录整洁。

然而，可能会有一些情况下，即使您没有 package.json，也需要在 Deno 项目中有一个本地的 node_modules 目录（例如，当使用像 Next.js 或 Svelte 这样的框架或依赖于使用 Node-API 的 npm 包时）。

默认 Deno 依赖行为 Jump to heading#

默认情况下，当您使用 deno run 命令时，Deno 不会创建 node_modules 目录，依赖项将安装到全局缓存中。这是针对新的 Deno 项目推荐的设置。

自动创建 node_modules Jump to heading#

如果您需要在项目中创建 node_modules 目录，您可以使用 --node-modules-dir 标志或在配置文件中使用 nodeModulesDir: auto 选项，告诉 Deno 在当前工作目录中创建一个 node_modules 目录：

deno run --node-modules-dir=auto main.ts

或通过配置文件：

{
  "nodeModulesDir": "auto"
}

自动模式会自动将依赖项安装到全局缓存，并在项目根目录创建一个本地的 node_modules 目录。对于依赖于 node_modules 目录的 npm 依赖的项目（大多数使用打包器或有 npm 依赖的 postinstall 脚本的项目），这被推荐。

手动创建 node_modules Jump to heading#

如果您的项目中有 package.json 文件，您可以使用手动模式，该模式需要一个安装步骤来创建您的 node_modules 目录：

deno install
deno run --node-modules-dir=manual main.ts

或通过配置文件：

{ "nodeModulesDir": "manual" }

然后您可以运行 deno install/npm install/pnpm install 或其他任何包管理器来创建 node_modules 目录。

手动模式是使用 package.json 的项目的默认模式。您可能会从 Node.js 项目中识别出这种工作流。它对于使用像 Next.js、Remix、Svelte、Qwik 等框架的项目，或使用 Vite、Parcel 或 Rollup 等工具的项目推荐。

Deno 1.X 的 node_modules Jump to heading#

使用 --node-modules-dir 标志。

例如，给定 main.ts：

import chalk from "npm:chalk@5";

console.log(chalk.green("Hello"));

deno run --node-modules-dir main.ts

运行上述命令时，加上 --node-modules-dir 标志，将在当前目录创建一个 node_modules 文件夹，具有类似 npm 的文件夹结构。

Node.js 全局对象 Jump to heading#

在 Node.js 中，有一些 全局对象 可用于所有程序的范围，这些对象特定于 Node.js，例如 process 对象。

以下是您可能在实际使用中遇到的一些全局对象以及如何在 Deno 中使用它们：

• process - Deno 提供了 process 全局，这是最常用的全局对象，在流行的 npm 包中使用广泛。它对所有代码都是可用的。然而，Deno 会通过提供 lint 警告和快速修复指导您显式从 node:process 模块导入它：

console.log(process.versions.deno);

$ deno run process.js
2.0.0
$ deno lint process.js
error[no-process-global]: NodeJS process global is discouraged in Deno
 --> /process.js:1:13
  |
1 | console.log(process.versions.deno);
  |             ^^^^^^^
  = hint: Add `import process from "node:process";`

  docs: https://docs.deno.com/lint/rules/no-process-global


Found 1 problem (1 fixable via --fix)
Checked 1 file

• require() - 请参见 CommonJS 支持

• Buffer - 要使用 Buffer API，必须显式从 node:buffer 模块导入：

import { Buffer } from "node:buffer";

const buf = new Buffer(5, "0");

建议使用 Uint8Array 或其他 TypedArray 子类。

• __filename - 使用 import.meta.filename 替代。

• __dirname - 使用 import.meta.dirname 替代。

Node-API 插件 Jump to heading#

Deno 支持 Node-API 插件，这些插件被流行的 npm 包使用，如 esbuild、npm:sqlite3 或 npm:duckdb。

您可以期望所有使用公共和文档 Node-API 的包都能正常工作。

自 Deno 2.0 以来，使用 Node-API 插件的 npm 包 仅在存在 node_modules/ 目录时支持。添加 "nodeModulesDir": "auto" 或 "nodeModulesDir": "manual" 设置到您的 deno.json 文件，或者使用 --node-modules-dir=auto|manual 标志运行，以确保这些包正常工作。在配置错误的情况下，Deno 会提供提示以说明如何解决此情况。

从 Node 迁移到 Deno Jump to heading#

在 Deno 中运行您的 Node.js 项目是一个简单的过程。在大多数情况下，您可以期望几乎不需要更改，如果您的项目使用 ES 模块编写。

需要注意的主要几点包括：

1. 导入 Node.js 内置模块需要 node: 前缀：

// ❌
import * as fs from "fs";
import * as http from "http";

// ✅
import * as fs from "node:fs";
import * as http from "node:http";

2. 一些 在 Node.js 中可用的全局对象 需要显式导入，例如 Buffer：

import { Buffer } from "node:buffer";

3. require() 仅在扩展名为 .cjs 的文件中可用，在其他文件中必须手动创建 require() 实例 需要创建。 npm 依赖可以在不考虑文件扩展名的情况下使用 require()。

运行脚本 Jump to heading#

Deno 原生支持运行 npm 脚本，通过 deno task 子命令（如果您从 Node.js 迁移，这类似于 npm run script 命令）。考虑以下有一个名为 start 的脚本的 Node.js 项目，它在其 package.json 内：

{
  "name": "my-project",
  "scripts": {
    "start": "eslint"
  }
}

您可以通过运行以下命令在 Deno 中执行此脚本：

deno task start

可选改进 Jump to heading#

Deno 的核心优势之一是统一的工具链，开箱即用地支持 TypeScript，和包括 linter、格式化程序以及测试运行器等工具。切换到 Deno 使您能够简化工具链，减少项目中动移动的部件数量。

配置

Deno 有自己的配置文件 deno.json 或 deno.jsonc，可用于配置您的项目。

您可以使用它来使用 imports 选项定义依赖项 - 您可以逐个迁移 package.json 中的依赖项，或者选择在配置文件中完全不定义它们，而在代码中使用 npm: 前缀。

除了指定依赖项，您还可以使用 deno.json 定义任务、lint 和格式选项、路径映射以及其他运行时配置。

Linting

Deno 自带一个内置 linter，性能优先考虑。它与 ESlint 相似，虽然规则数量有限。如果您不依赖于 ESLint 插件，您可以从 package.json 的 devDependencies 部分删除 eslint 依赖，并改为使用 deno lint。

Deno 可以在几毫秒内 lint 大型项目。您可以通过运行以下命令在项目上尝试：

deno lint

这将对您项目中的所有文件进行 lint。 当 linter 检测到问题时，它将在您的编辑器和终端输出中显示该行。如下所示的示例：

error[no-constant-condition]: Use of a constant expressions as conditions is not allowed.
 --> /my-project/bar.ts:1:5
  |
1 | if (true) {
  |     ^^^^
  = hint: Remove the constant expression

  docs: https://docs.deno.com/lint/rules/no-constant-condition


Found 1 problem
Checked 4 files

许多 lint 问题可以通过传递 --fix 标志自动修复：

deno lint --fix

所有支持的 linting 规则的完整列表可以在 https://docs.deno.com/lint/ 找到。要了解更多关于如何配置 linter的信息，请查看 deno lint 子命令。

格式化

Deno 配备了一个 内置格式化工具，可以选择根据 Deno 风格指南格式化您的代码。您可以取代将 prettier 添加到 devDependencies，而是使用 Deno 的内置零配置代码格式化器 deno fmt。

您可以通过运行以下命令在项目上运行格式化程序：

deno fmt

如果在 CI 中使用 deno fmt，也可以传递 --check 参数，当检测到格式不正确的代码时使格式化程序退出并显示错误。

deno fmt --check

格式化规则可以在您的 deno.json 文件中配置。要了解有关如何配置格式化程序的更多信息，请查看 deno fmt 子命令。

测试

Deno 鼓励为您的代码编写测试，并提供一个内置的测试运行器，使编写和运行测试变得容易。测试运行器与 Deno 紧密集成，因此您不需要额外的配置就能使 TypeScript 或其他功能正常工作。

Deno.test("my test", () => {
  // Your test code here
});

deno test

传递 --watch 标志时，当导入的任何模块发生变化时，测试运行器将自动重新加载。

要了解有关测试运行器的更多信息以及如何配置它，请查看 deno test 子命令 文档。

私有仓库 Jump to heading#

Deno 支持私有仓库，这允许您托管和共享自己的模块。这对于希望将其代码保持私密的组织或希望与特定人员分享代码的个人非常有用。

什么是私有仓库？ Jump to heading#

大型组织通常会托管自己的私有 npm 仓库，以安全地管理内部包。这些私有仓库作为存储库，通过它们组织可以发布和存储其专有或自定义包。与公共 npm 仓库不同，私有仓库仅对组织内的授权用户可访问。

如何在 Deno 中使用私有仓库 Jump to heading#

首先，配置您项目中的 .npmrc 文件，以指向您的私有仓库。 .npmrc 文件必须位于项目根目录或 $HOME 目录中。在 .npmrc 文件中添加以下内容：

@mycompany:registry=http://mycompany.com:8111/
//mycompany.com:8111/:_auth=secretToken

将 http://mycompany.com:8111/ 替换为您的私有仓库的实际 URL，并将 secretToken 替换为您的身份验证令牌。

然后，更新您的 deno.json 或 package.json 以指定您私有包的导入路径。例如：

{
  "imports": {
    "@mycompany/package": "npm:@mycompany/package@1.0.0"
  }
}

或者如果您正在使用 package.json：

{
  "dependencies": {
    "@mycompany/package": "1.0.0"
  }
}

现在您可以在 Deno 代码中导入您的私有包：

import { hello } from "@mycompany/package";

console.log(hello());

并通过以下命令运行：

deno run main.ts

从 Node 到 Deno 速查表 Jump to heading#

¹ 类型检查是自动进行的，TypeScript 编译器已内置在 deno 二进制文件中。