deno.com
本页内容

工作区和 Monorepos

Deno 支持工作区,也称为“Monorepos”,它允许您同时管理多个相关和相互依赖的包。

“工作区”是包含 deno.jsonpackage.json 配置文件的一系列文件夹。根 deno.json 文件定义了工作区

deno.json
{
  "workspace": ["./add", "./subtract"]
}

此配置使用 addsubtract 成员配置工作区,这些成员是预期包含 deno.json(c) 和/或 package.json 文件的目录。

命名

Deno 使用 workspace 而不是 npm 的 workspaces 来表示具有多个成员的单个工作区。

示例 跳转到标题

让我们扩展 deno.json 工作区示例,看看它的功能。文件层次结构如下所示

/
├── deno.json
├── main.ts
├── add/
│     ├── deno.json
│     └── mod.ts
└── subtract/
      ├── deno.json
      └── mod.ts

有两个工作区成员(add 和 subtract),每个成员都有 mod.ts 文件。还有一个根 deno.json 和一个 main.ts

顶层 deno.json 配置文件定义了工作区和一个应用于所有成员的顶层导入映射

deno.json
{
  "workspace": ["./add", "./subtract"],
  "imports": {
    "chalk": "npm:chalk@5"
  }
}

main.ts 文件使用导入映射中的 chalk 裸标识符,并从工作区成员导入 addsubtract 函数。请注意,它使用 @scope/add@scope/subtract 导入它们,即使这些不是正确的 URL 并且不在导入映射中。它们是如何解析的?

main.ts
import chalk from "chalk";
import { add } from "@scope/add";
import { subtract } from "@scope/subtract";

console.log("1 + 2 =", chalk.green(add(1, 2)));
console.log("2 - 4 =", chalk.red(subtract(2, 4)));

add/ 子目录中,我们定义了一个带有 "name" 字段的 deno.json,这对于引用工作区成员非常重要。deno.json 文件还包含示例配置,例如在使用 deno fmt 时关闭分号。

add/deno.json
{
  "name": "@scope/add",
  "version": "0.1.0",
  "exports": "./mod.ts",
  "fmt": {
    "semiColons": false
  }
}
add/mod.ts
export function add(a: number, b: number): number {
  return a + b;
}

subtract/ 子目录类似,但没有相同的 deno fmt 配置。

subtract/deno.json
{
  "name": "@scope/subtract",
  "version": "0.3.0",
  "exports": "./mod.ts"
}
subtract/mod.ts
import { add } from "@scope/add";

export function subtract(a: number, b: number): number {
  return add(a, b * -1);
}

让我们运行它

> deno run main.ts
1 + 2 = 3
2 - 4 = -2

这里有很多内容需要解释,展示了一些 Deno 工作区功能

  1. 这个 monorepo 由两个包组成,分别放置在 ./add./subtract 目录中。

  2. 通过在成员的 deno.json 文件中使用 nameversion 选项,可以在整个工作区中使用“裸标识符”来引用它们。在本例中,这些包被命名为 @scope/add@scope/subtract,其中 scope 是您可以选择的“作用域”名称。有了这两个选项,就不需要在 import 语句中使用长而相对的文件路径。

  3. npm:chalk@5 包是整个工作区中的共享依赖项。工作区成员“继承”工作区根目录的 imports,从而可以轻松管理整个代码库中依赖项的单个版本。

  4. add 子目录在其 deno.json 中指定 deno fmt 在格式化代码时不应应用分号。这使得现有项目的迁移更加顺畅,而无需一次性更改数十或数百个文件。


Deno 工作区非常灵活,可以与 Node 包一起使用。为了简化现有 Node.js 项目的迁移,您可以在单个工作区中同时拥有 Deno-first 和 Node-first 包。

Deno 如何解析工作区依赖项 跳转到标题

当在工作区中运行从另一个工作区成员导入的项目时,Deno 按照以下步骤解析依赖项

  1. Deno 从正在执行的项目目录(例如,项目 A)开始
  2. 它在父目录中查找根 deno.json 文件
  3. 如果找到,它会检查该文件中的 workspace 属性
  4. 对于项目 A 中的每个 import 语句,Deno 检查导入是否与任何工作区成员的 deno.json 中定义的包名称匹配
  5. 如果找到匹配的包名称,Deno 会验证包含目录是否列在根工作区配置中
  6. 然后,使用工作区成员的 deno.json 中的 exports 字段将导入解析为正确的文件

例如,给定以下结构

/
├── deno.json         # workspace: ["./project-a", "./project-b"]
├── project-a/
│   ├── deno.json     # name: "@scope/project-a"
│   └── mod.ts        # imports from "@scope/project-b"
└── project-b/
    ├── deno.json     # name: "@scope/project-b"
    └── mod.ts

project-a/mod.ts"@scope/project-b" 导入时,Deno

  1. 看到 import 语句
  2. 检查父目录的 deno.json
  3. 在工作区数组中找到 project-b
  4. 验证 project-b/deno.json 存在并且具有匹配的包名称
  5. 使用 project-b 的 exports 解析导入

容器化的重要提示 跳转到标题

当容器化依赖于其他工作区成员的工作区成员时,您必须包含

  1. deno.json 文件
  2. 所有依赖的工作区包
  3. 与您的开发环境相同的目录结构

例如,如果 docker 化上面的 project-a,您的 Dockerfile 应该

COPY deno.json /app/deno.json
COPY project-a/ /app/project-a/
COPY project-b/ /app/project-b/

这保留了 Deno 用于查找和导入工作区依赖项的工作区解析机制。

多个包入口 跳转到标题

到目前为止,我们的包只有一个入口。对于简单的包来说,这很好,但通常您会希望有多个入口来对包的相关方面进行分组。这可以通过将 object 而不是 string 传递给 exports 来完成

my-package/deno.json
{
  "name": "@scope/my-package",
  "version": "0.3.0",
  "exports": {
    ".": "./mod.ts",
    "./foo": "./foo.ts",
    "./other": "./dir/other.ts"
  }
}

"." 条目是导入 @scope/my-package 时选择的默认条目。因此,上面的 deno.json 示例提供了以下条目

  • @scope/my-package
  • @scope/my-package/foo
  • @scope/my-package/other

npm 工作区迁移 跳转到标题

Deno 工作区支持从现有的 npm 包中使用 Deno-first 包。在此示例中,我们将 Deno 库 @deno/hi 与我们几年前开发的 Node.js 库 @deno/log 混合搭配使用。

我们需要在根目录中包含一个 deno.json 配置文件

deno.json
{
  "workspace": {
    "members": ["hi"]
  }
}

以及我们现有的 package.json 工作区

package.json
{
  "workspaces": ["log"]
}

该工作区当前有一个 log npm 包

log/package.json
{
  "name": "@deno/log",
  "version": "0.5.0",
  "type": "module",
  "main": "index.js"
}
log/index.js
export function log(output) {
  console.log(output);
}

让我们创建一个导入 @deno/log@deno/hi Deno-first 包

hi/deno.json
{
  "name": "@deno/hi",
  "version": "0.2.0",
  "exports": "./mod.ts",
  "imports": {
    "log": "npm:@deno/log@^0.5"
  }
}
hi/mod.ts
import { log } from "log";

export function sayHiTo(name: string) {
  log(`Hi, ${name}!`);
}

现在,我们可以编写一个导入并调用 himain.ts 文件

main.ts
import { sayHiTo } from "@deno/hi";

sayHiTo("friend");
$ deno run main.ts
Hi, friend!

您甚至可以在现有的 Node.js 包中同时拥有 deno.jsonpackage.json。此外,您可以删除根目录中的 package.json,并在 deno.json 工作区成员中指定 npm 包。这允许您逐步迁移到 Deno,而无需进行大量前期工作。

例如,您可以添加类似 log/deno.json 的内容来配置 Deno 的代码检查器和格式化程序

{
  "fmt": {
    "semiColons": false
  },
  "lint": {
    "rules": {
      "exclude": ["no-unused-vars"]
    }
  }
}

在工作区中运行 deno fmt 将格式化 log 包,使其不包含任何分号,如果您在其中一个源文件中留下未使用的变量,deno lint 也不会报错。

配置内置 Deno 工具 跳转到标题

某些配置选项仅在工作区根目录中才有意义,例如。在一个成员中指定 nodeModulesDir 选项不可用,如果某个选项需要在工作区根目录中应用,Deno 会发出警告。

以下是工作区根目录及其成员中可用的各种 deno.json 选项的完整矩阵

选项 工作区 注释
compilerOptions 目前,每个工作区我们只允许一组 compilerOptions。这是因为需要对 deno_graph 和 TSC 集成进行多处更改才能允许多组。此外,我们还必须确定哪些 compilerOptions 应用于远程依赖项。我们可以在未来重新审视这一点。
importMap 与每个配置文件的 imports 和 scopes 互斥。此外,工作区配置中不支持 importMap,包配置中不支持 imports。
imports 与每个配置文件的 importMap 互斥。
scopes 与每个配置文件的 importMap 互斥。
exclude
lint.include
lint.exclude
lint.files ⚠️ 已弃用
lint.rules.tags 标签通过将包附加到工作区列表来合并。重复项将被忽略。
lint.rules.include
lint.rules.exclude 规则按包合并,包优先于工作区(包 include 强于工作区 exclude)。
lint.report 一次只能有一个 reporter 处于活动状态,因此如果对跨多个包的文件进行代码检查,则不允许每个工作区使用不同的 reporter。
fmt.include
fmt.exclude
fmt.files ⚠️ 已弃用
fmt.useTabs 包优先于工作区。
fmt.indentWidth 包优先于工作区。
fmt.singleQuote 包优先于工作区。
fmt.proseWrap 包优先于工作区。
fmt.semiColons 包优先于工作区。
fmt.options.* ⚠️ 已弃用
nodeModulesDir 解析行为在整个工作区中必须相同。
vendor 解析行为在整个工作区中必须相同。
tasks 包任务优先于工作区任务。使用的 cwd 是任务所在的配置文件的 cwd。
test.include
test.exclude
test.files ⚠️ 已弃用
publish.include
publish.exclude
bench.include
bench.exclude
bench.files ⚠️ 已弃用
lock 每个解析器只能存在一个 lock 文件,每个工作区只能存在一个解析器,因此按包有条件地启用 lockfile 没有意义。
unstable 为了简单起见,我们不允许不稳定的标志,因为 CLI 的很多部分都假定不稳定的标志是不可变的,并且对整个过程都是全局的。与 DENO_UNSTABLE_* 标志的交互也很奇怪。
name
version
exports
workspace 不支持嵌套工作区。

您找到所需的信息了吗?

隐私政策