Modules and dependencies

Deno 使用 ECMAScript 模块 作为其默认模块系统，以符合现代 JavaScript 标准并提升更高效和一致的开发体验。这是 JavaScript 模块的官方标准，允许更好的树摇优化，改进的工具集成，以及在不同环境中的原生支持。

通过采用 ECMAScript 模块，Deno 确保与不断发展的 JavaScript 生态系统的兼容性。对开发者而言，这意味着一个流畅且可预测的模块系统，避免了与遗留模块格式（如 CommonJS）相关的复杂性。

导入模块 Jump to heading#

在这个例子中，add 函数是从本地的 calc.ts 模块导入的。

export function add(a: number, b: number): number {
  return a + b;
}

// 导入与此文件相邻的 `calc.ts` 模块
import { add } from "./calc.ts";

console.log(add(1, 2)); // 3

你可以在包含 main.ts 和 calc.ts 的目录中运行这个例子，通过调用 deno run main.ts。

使用 ECMAScript 模块时，本地导入规范必须始终包含完整的文件扩展名，不能省略。

// 错误：缺少文件扩展名
import { add } from "./calc";

// 正确：包含文件扩展名
import { add } from "./calc.ts";

Import attributes Jump to heading#

Deno supports the with { type: "json" } import attribute syntax for importing JSON files:

import data from "./data.json" with { type: "json" };

console.log(data.property); // Access JSON data as an object

This is the only import attribute type currently supported in Deno. Support for type: text and type: bytes is being considered for future updates, and currently waiting on the Module Harmony proposal.

导入第三方模块和库 Jump to heading#

在 Deno 中处理第三方模块时，使用与本地代码相同的 import 语法。第三方模块通常是从远程注册中心导入，并以 jsr:、npm: 或 https:// 开头。

import { camelCase } from "jsr:@luca/cases@1.0.0";
import { say } from "npm:cowsay@1.6.0";
import { pascalCase } from "https://deno.land/x/case/mod.ts";

Deno 推荐使用 JSR，这是一个现代的 JavaScript 注册中心，用于第三方模块。在那里，你将会找到许多文档完善的 ES 模块供你的项目使用，包括 Deno 标准库。

你可以 在这里阅读更多关于 Deno 对 npm 包支持的内容。

管理第三方模块和库 Jump to heading#

在多个文件中导入模块时，输入模块名称和完整版本说明符可能会变得繁琐。你可以通过在 deno.json 文件中使用 imports 字段来集中管理远程模块。我们将这个 imports 字段称为 导入映射（import map），它基于 导入映射标准。

{
  "imports": {
    "@luca/cases": "jsr:@luca/cases@^1.0.0",
    "cowsay": "npm:cowsay@^1.6.0",
    "cases": "https://deno.land/x/case/mod.ts"
  }
}

使用重新映射的说明符，代码看起来更加简洁：

import { camelCase } from "@luca/cases";
import { say } from "cowsay";
import { pascalCase } from "cases";

重新映射名称可以是任何有效的说明符。这是 Deno 中一个非常强大的功能，可以重新映射任何内容。了解更多关于导入映射可以做什么的信息 这里。

区分 deno.json 中的 imports 或 importMap 选项和 --import-map 选项 Jump to heading#

[导入映射标准]要求每个模块有两个条目：一个是模块说明符，另一个是带有尾随 / 的说明符。这是因为该标准只允许每个模块说明符一个条目，而尾随的 / 表示该说明符指代一个目录。例如，当使用 --import-map import_map.json 选项时，import_map.json 文件必须为每个模块包含这两个条目（注意使用 jsr:/@std/async 而不是 jsr:@std/async）：

{
  "imports": {
    "@std/async": "jsr:@std/async@^1.0.0",
    "@std/async/": "jsr:/@std/async@^1.0.0/"
  }
}

deno.json 中 importMap 字段引用的 import_map.json 文件的行为与使用 --import-map 选项完全相同，包含的每个模块的条目要求与上面所示相同。

相比之下，deno.json 扩展了导入映射标准。当你在 deno.json 中使用 imports 字段或通过 importMap 字段引用 import_map.json 文件时，你只需要指定模块说明符而不带尾随 /：

{
  "imports": {
    "@std/async": "jsr:@std/async@^1.0.0"
  }
}

使用 deno add 添加依赖 Jump to heading#

使用 deno add 子命令可以轻松完成安装过程。它将自动将你请求的包的最新版本添加到 deno.json 的 imports 部分。

# 将模块的最新版本添加到 deno.json
$ deno add jsr:@luca/cases
Add @luca/cases - jsr:@luca/cases@1.0.0

{
  "imports": {
    "@luca/cases": "jsr:@luca/cases@^1.0.0"
  }
}

你也可以指定确切的版本：

# 传入确切版本
$ deno add jsr:@luca/cases@1.0.0
Add @luca/cases - jsr:@luca/cases@1.0.0

在 deno add 参考文档 中阅读更多内容。

你也可以使用 deno remove 移除依赖项：

$ deno remove @luca/cases
Remove @luca/cases

{
  "imports": {}
}

在 deno remove 参考文档 中阅读更多内容。

包版本 Jump to heading#

你可以为正在导入的包指定一个版本范围。这通过 @ 符号后跟版本范围说明符来完成，并遵循 semver 版本方案。

例如：

@scopename/mypackage           # 最高版本
@scopename/mypackage@16.1.0    # 精确版本
@scopename/mypackage@16        # 最高的 16.x 版本 >= 16.0.0
@scopename/mypackage@^16.1.0   # 最高的 16.x 版本 >= 16.1.0
@scopename/mypackage@~16.1.0   # 最高的 16.1.x 版本 >= 16.1.0

以下是所有你可以指定版本或范围的方式的概述：

HTTPS 导入 Jump to heading#

Deno 还支持引用 HTTP/HTTPS URL 的导入语句，可以直接：

import { Application } from "https://deno.land/x/oak/mod.ts";

或作为你的 deno.json 导入映射的一部分：

{
  "imports": {
    "oak": "https://deno.land/x/oak/mod.ts"
  }
}

支持 HTTPS 导入使我们能够支持以下 JavaScript CDN，因为它们提供对 JavaScript 模块的 URL 访问：

• deno.land/x
• esm.sh
• unpkg.com

HTTPS 导入在你的项目是一个小型且通常是单文件的 Deno 项目时非常有用，因为不需要其他配置。使用 HTTPS 导入，你可以完全避免拥有 deno.json 文件。然而，在更大的应用中建议不要使用这种导入方式，因为你可能会遇到版本冲突（不同的文件使用不同的版本说明符）。

覆盖依赖 Jump to heading#

Deno 提供机制来覆盖依赖项，使开发者在开发或测试期间使用自定义或本地版本库。

注意：如果你需要在构建之间缓存和修改本地依赖项，考虑对远程模块进行 vendoring。

覆盖本地 JSR 包 Jump to heading#

对于熟悉 Node.js 中 npm link 的开发者，Deno 通过 deno.json 中的 patch 字段提供了类似的功能。这允许你在开发期间使用本地版本覆盖依赖项，而不需要发布它们。

示例：

{
  "patch": [
    "../some-package-or-workspace"
  ]
}

关键点：

• patch 字段接受包含 JSR 包或工作区的目录的路径。如果你在工作区内引用单个包，整个工作区都会被包含。
• 此功能仅在工作区根目录中被尊重。在其他地方使用 patch 会触发警告。
• 目前，patch 限制为 JSR 包。尝试对 npm 包进行修补将导致警告且没有效果。

限制：

• 暂不支持 npm 包覆盖。这计划在未来更新中实现。
• 基于 Git 的依赖覆盖不可用。
• patch 字段需要在工作区根目录中进行适当配置。
• 此功能仍在实验阶段，可能会根据用户反馈进行更改。

覆盖 NPM 包 Jump to heading#

我们计划支持带有上述修补功能的 NPM 包，但在此之前，如果你有一个 node_modules 目录，可以在不更改的情况下使用 npm link 来实现相同效果。通常这通过在 deno.json 文件中设置 { "nodeModulesDir": "manual" } 来完成。另请参见 node_modules 的文档。

覆盖 HTTPS 导入 Jump to heading#

Deno 还允许通过 deno.json 中的 importMap 字段覆盖 HTTPS 导入。当将远程依赖项替换为本地修补版本以进行调试或临时修复时，此功能特别有用。

示例：

{
  "imports": {
    "example/": "https://deno.land/x/example/"
  },
  "scopes": {
    "https://deno.land/x/example/": {
      "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts"
    }
  }
}

关键点：

• 导入映射中的 scopes 字段允许你将特定导入重定向到其他路径。
• 这通常用于使用本地文件覆盖远程依赖项以进行测试或开发目的。
• 导入映射仅适用于项目的根目录。依赖项中的嵌套导入映射会被忽略。

Vendoring 远程模块 Jump to heading#

如果你的项目具有外部依赖项，你可能希望将它们存储在本地，以避免每次构建项目时都从互联网下载它们。这在你在 CI 服务器或 Docker 容器中构建项目时尤其有用，或者需要修补或以其他方式修改远程依赖项。

Deno 通过在 deno.json 文件中设置以下功能来提供此功能：

{
  "vendor": true
}

将上述代码段添加到你的 deno.json 文件中，Deno 将在项目运行时将所有依赖项缓存到 vendor 目录中，或者你可以选择运行 deno install --entrypoint 命令以立即缓存依赖项：

deno install --entrypoint main.ts

然后你可以像往常一样使用 deno run 运行应用程序：

deno run main.ts

在进行 vendoring 后，你可以使用 --cached-only 标志在没有互联网访问的情况下运行 main.ts，这会强制 Deno 仅使用本地可用的模块。

有关更加高级的覆盖，例如在开发期间替代依赖项，请参见 覆盖依赖。

发布模块 Jump to heading#

任何定义导出的 Deno 程序都可以作为模块发布。这允许其他开发人员在自己的项目中导入和使用你的代码。模块可以发布到：

• JSR - 推荐，原生支持 TypeScript，并为你自动生成文档
• npm - 使用 dnt 创建 npm 包
• deno.land/x - 用于 HTTPS 导入，尽可能使用 JSR，而不是

重新加载模块 Jump to heading#

默认情况下，Deno 使用全局缓存目录（DENO_DIR）来存储下载的依赖项。这个缓存共享于所有项目。

你可以使用 --reload 标志强制 Deno 重新获取并重新编译模块到缓存中。

# 重新加载所有内容
deno run --reload my_module.ts

# 重新加载特定模块
deno run --reload=jsr:@std/fs my_module.ts

只使用缓存模块 Jump to heading#

要强制 Deno 只使用之前已缓存的模块，请使用 --cached-only 标志：

deno run --cached-only mod.ts

如果有任何依赖于 mod.ts 的依赖树中的依赖项尚未缓存，这将失败。

完整性检查和锁文件 Jump to heading#

想象一下，你的模块依赖于位于 https://some.url/a.ts 的远程模块。当你第一次编译模块时，a.ts 被获取、编译并缓存。此缓存版本将在你在不同机器上运行模块（例如在生产环境中）或手动重新加载缓存（使用命令，如 deno install --reload）之前使用。

但是如果 https://some.url/a.ts 的内容发生变化呢？这可能导致你的生产模块与本地模块运行的依赖代码不同。为了检测这一点，Deno 使用完整性检查和锁文件。

Deno 使用 deno.lock 文件检查外部模块的完整性。要启用锁文件，应该做到以下两点之一：

1. 在当前或祖先目录中创建 deno.json 文件，这将自动创建一个附加锁文件 deno.lock。

   注意，可以通过在 deno.json 中指定以下内容来禁用此功能：

   deno.json

   {
     "lock": false
   }
   

2. 使用 --lock 标志以启用并指定锁文件检查。

冻结锁文件 Jump to heading#

默认情况下，Deno 使用附加锁文件，新的依赖项将被添加到锁文件中，而不是发生错误。

在某些情况下（例如 CI 流水线或生产环境），这可能并不是所希望的，在这些情况下你希望 Deno 在遇到从未见过的依赖项时报错。为此，你可以指定 --frozen 标志，或在 deno.json 文件中设置以下内容：

{
  "lock": {
    "frozen": true
  }
}

在使用冻结的锁文件运行 deno 命令时，任何尝试用新内容更新锁文件的操作都会导致命令退出，并显示将要进行的修改的错误信息。

如果你希望更新锁文件，可以在命令行中指定 --frozen=false ，以暂时禁用冻结锁文件。

更改锁文件路径 Jump to heading#

可以通过指定 --lock=deps.lock 或在 Deno 配置文件中设置以下内容来配置锁文件路径：

{
  "lock": {
    "path": "deps.lock"
  }
}

私有仓库 Jump to heading#

可能会有一些情况，你希望加载位于 私有 仓库中的远程模块，例如 GitHub 中的私有仓库。

Deno 支持在请求远程模块时发送 bearer token。Bearer tokens 是与 OAuth 2.0 一起使用的主流访问令牌类型，并且广泛得到托管服务的支持（例如 GitHub、GitLab、Bitbucket、Cloudsmith 等）。

DENO_AUTH_TOKENS Jump to heading#

Deno CLI 将寻找名为 DENO_AUTH_TOKENS 的环境变量，以确定应考虑使用哪些身份验证令牌来请求远程模块。环境变量的值格式为 n 数量的令牌，由分号（;）分隔，其中每个令牌可以是：

• 格式为 {token}@{hostname[:port]} 的 bearer token，或者
• 格式为 {username}:{password}@{hostname[:port]} 的基本认证数据

例如，单个令牌对于 deno.land 看起来像这样：

DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land

或者：

DENO_AUTH_TOKENS=username:password@deno.land

多个令牌则看起来像这样：

DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land;f1e2d3c4b5a6@example.com:8080;username:password@deno.land

当 Deno 前往获取一个远程模块时，如果主机名与远程模块的主机名匹配，Deno 将把请求的 Authorization 头设置为 Bearer {token} 或 Basic {base64EncodedData} 的值。这允许远程服务器识别请求是与特定已认证用户关联的授权请求，并提供对服务器上适当资源和模块的访问。

GitHub Jump to heading#

要访问 GitHub 上的私有仓库，你需要为自己发放一个 个人访问令牌。你可以通过登录 GitHub 并进入 设置 -> 开发者设置 -> 个人访问令牌：

然后选择 生成新令牌，为你的令牌提供描述，并相应地授予 repo 权限。repo 权限将使你能够读取文件内容（有关 GitHub 中作用域的更多信息）：

创建后，GitHub 将仅显示新令牌一次，此时你要在环境变量中使用的值：

为了访问包含在 GitHub 私有仓库中的模块，你需要在环境变量 DENO_AUTH_TOKENS 中使用发放的令牌，作用域为 raw.githubusercontent.com 主机名。例如：

DENO_AUTH_TOKENS=a1b2c3d4e5f6@raw.githubusercontent.com

这应该允许 Deno 访问任何由该令牌发放用户可以访问的模块。

当令牌不正确或用户没有访问模块的权限时，GitHub 将发出 404 Not Found 状态，而不是未授权状态。因此，如果你在命令行中收到访问模块未找到的错误，请检查环境变量设置和个人访问令牌设置。

此外，deno run -L debug 应该打印出关于从环境变量解析出的令牌数量的调试信息。如果它觉得任何令牌格式错误，它会打印错误消息。但出于安全原因，它不会打印任何令牌的详细信息。