deno.json 和 package.json

您可以使用 deno.json 文件配置 Deno。此文件可用于配置 TypeScript 编译器、代码检查器、格式化程序以及其他 Deno 工具。

配置文件支持 .json 和 .jsonc 扩展名。

如果 deno.json 或 deno.jsonc 配置文件位于您当前的工作目录或其父目录中，Deno 将自动检测到它们。您可以使用 --config 标志指定不同的配置文件。

支持 package.json 跳转到标题#

Deno 也支持 package.json 文件，以兼容 Node.js 项目。如果您有一个 Node.js 项目，则无需创建 deno.json 文件。Deno 将使用 package.json 文件来配置项目。

如果 deno.json 和 package.json 文件都存在于同一个目录中，Deno 将理解在 deno.json 和 package.json 中指定的依赖项；并使用 deno.json 文件进行 Deno 特定的配置。阅读更多关于 Deno 中的 Node 兼容性。

依赖项 跳转到标题#

您 deno.json 文件中的 "imports" 字段允许您指定项目中使用的依赖项。您可以使用它将裸说明符（bare specifier）映射到 URL 或文件路径，从而更轻松地管理应用程序中的依赖项和模块解析。

例如，如果您想在项目中使用标准库中的 assert 模块，可以使用此导入映射

{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "chalk": "npm:chalk@5"
  }
}

然后您的脚本可以使用裸说明符 std/assert

import { assertEquals } from "@std/assert";
import chalk from "chalk";

assertEquals(1, 2);
console.log(chalk.yellow("Hello world"));

您也可以在 package.json 中使用 "dependencies" 字段

{
  "dependencies": {
    "express": "express@^1.0.0"
  }
}

import express from "express";

const app = express();

请注意，这需要您运行 deno install。

阅读更多关于 模块导入和依赖项

自定义路径映射 跳转到标题#

deno.json 中的导入映射可用于更通用的说明符路径映射。您可以将精确的说明符直接映射到第三方模块或文件，也可以将导入说明符的一部分映射到目录。

{
  "imports": {
    // Map to an exact file
    "foo": "./some/long/path/foo.ts",
    // Map to a directory, usage: "bar/file.ts"
    "bar/": "./some/folder/bar/"
  }
}

用法

import * as foo from "foo";
import * as bar from "bar/file.ts";

导入说明符的路径映射通常在大型代码库中用于简化。

要将项目根目录用于绝对导入

{
  "imports": {
    "/": "./",
    "./": "./"
  }
}

import { MyUtil } from "/util.ts";

这将使以 / 开头的导入说明符相对于导入映射的 URL 或文件路径进行解析。

覆盖包 跳转到标题#

deno.json 中的 links 字段允许您使用存储在磁盘上的本地包来覆盖依赖项。这类似于 npm link。

{
  "links": [
    "../some-package"
  ]
}

此功能解决了几个常见的开发挑战

• 依赖项错误修复
• 私有本地库
• 兼容性问题

被引用的包完全不需要发布。它只需要在 deno.json 或 package.json 中拥有正确的包名和元数据，以便 Deno 知道它正在处理哪个包。这提供了更大的灵活性和模块化，同时保持了您的主代码与外部包之间的清晰分离。

任务 跳转到标题#

您 deno.json 文件中的 tasks 字段用于定义可以通过 deno task 命令执行的自定义命令，并允许您根据项目的特定需求调整命令和权限。

它类似于 package.json 文件中的 scripts 字段，该字段也受支持。

{
  "tasks": {
    "start": "deno run --allow-net --watch=static/,routes/,data/ dev.ts",
    "test": "deno test --allow-net",
    "lint": "deno lint"
  }
}

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build"
  }
}

要执行任务，请使用 deno task 命令，后跟任务名称。例如

deno task start
deno task test
deno task lint
deno task dev
deno task build

阅读更多关于 deno task。

代码检查 跳转到标题#

deno.json 文件中的 lint 字段用于配置 Deno 内置代码检查器的行为。这允许您指定要包含或排除哪些文件进行代码检查，以及自定义代码检查规则以适应您的项目需求。

例如

{
  "lint": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"],
    "rules": {
      "tags": ["recommended"],
      "include": ["ban-untagged-todo"],
      "exclude": ["no-unused-vars"]
    }
  }
}

此配置将

• 只对 src/ 目录中的文件进行代码检查，
• 不对 src/testdata/ 目录中的文件或 src/fixtures/ 目录中的任何 TypeScript 文件进行代码检查。
• 指定应应用推荐的代码检查规则，
• 添加 ban-untagged-todo 规则，并且
• 排除 no-unused-vars 规则。

您可以在规则列表文档页面中找到所有可用的代码检查规则。

阅读更多关于 使用 Deno 进行代码检查。

格式化 跳转到标题#

deno.json 文件中的 fmt 字段用于配置 Deno 内置代码格式化程序的行为。这允许您自定义代码的格式化方式，确保项目的一致性，使其更易于阅读和协作。以下是您可以配置的关键选项：

{
  "fmt": {
    "useTabs": true,
    "lineWidth": 80,
    "indentWidth": 4,
    "semiColons": true,
    "singleQuote": true,
    "proseWrap": "preserve",
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  }
}

此配置将

• 使用制表符代替空格进行缩进，
• 将行限制为 80 个字符，
• 使用 4 个空格的缩进宽度，
• 在语句末尾添加分号，
• 对字符串使用单引号，
• 保留散文换行，
• 格式化 src/ 目录中的文件，
• 排除 src/testdata/ 目录中的文件以及 src/fixtures/ 目录中的任何 TypeScript 文件。

阅读更多关于 使用 Deno 格式化代码。

锁定文件 跳转到标题#

deno.json 文件中的 lock 字段用于指定 Deno 用于确保依赖项完整性的锁定文件的配置。锁定文件记录了您的项目所依赖的模块的确切版本和完整性哈希，确保每次运行项目时都使用相同的版本，即使依赖项在远程更新或更改。

{
  "lock": {
    "path": "./deno.lock",
    "frozen": true
  }
}

此配置将

• 指定锁定文件位置为 ./deno.lock（这是默认值，可以省略）
• 告诉 Deno 如果任何依赖项发生更改，则报错

Deno 默认使用锁定文件，您可以通过以下配置禁用它

{
  "lock": false
}

Node 模块目录 跳转到标题#

默认情况下，如果您的项目目录中存在 package.json 文件，Deno 会使用本地 node_modules 目录。

您可以通过 deno.json 文件中的 nodeModulesDir 字段控制此行为。

{
  "nodeModulesDir": "auto"
}

您可以将此字段设置为以下值

不需要指定此设置，将应用以下默认值

• 如果项目目录中没有 package.json 文件，则为 "none"
• 如果项目目录中有 package.json 文件，则为 "manual"

使用工作区时，此设置只能在工作区根目录中使用。在任何成员中指定它将导致警告。"manual" 设置只有在工作区根目录中存在 package.json 文件时才会自动应用。

TypeScript 编译器选项 跳转到标题#

deno.json 文件中的 compilerOptions 字段用于配置您的 Deno 项目的 TypeScript 编译器设置。这允许您自定义 TypeScript 代码的编译方式，确保其符合您的项目要求和编码标准。

另请参阅 在 Deno 中配置 TypeScript。

不稳定特性 跳转到标题#

deno.json 文件中的 unstable 字段用于为您的 Deno 项目启用特定的不稳定特性。

这些特性仍在开发中，尚未成为稳定 API 的一部分。通过在 unstable 数组中列出特性，您可以在它们正式发布之前进行实验和使用这些新功能。

{
  "unstable": ["cron", "kv", "webgpu"]
}

了解更多.

include 和 exclude 跳转到标题#

许多配置（例如 lint、fmt）都具有 include 和 exclude 属性，用于指定要包含的文件。

include 跳转到标题#

只包含此处指定的路径或模式。

{
  "lint": {
    // only format the src/ directory
    "include": ["src/"]
  }
}

exclude 跳转到标题#

此处指定的路径或模式将被排除。

{
  "lint": {
    // don't lint the dist/ folder
    "exclude": ["dist/"]
  }
}

这比 include 具有更高的优先级，如果路径在 include 和 exclude 中都匹配，则 exclude 将胜出。

您可能希望排除一个目录，但包含一个子目录。在 Deno 1.41.2+ 中，您可以通过在更通用的排除项下方指定一个否定的 glob 来取消排除更具体的路径

{
  "fmt": {
    // don't format the "fixtures" directory,
    // but do format "fixtures/scripts"
    "exclude": [
      "fixtures",
      "!fixtures/scripts"
    ]
  }
}

顶层 exclude 跳转到标题#

如果您有一个目录是您不希望 Deno 进行格式化、代码检查、类型检查、LSP 分析等操作的，那么请将其指定在顶层 exclude 数组中

{
  "exclude": [
    // exclude the dist folder from all sub-commands and the LSP
    "dist/"
  ]
}

有时您可能会发现您想取消排除顶层 exclude 中已排除的路径或模式。在 Deno 1.41.2+ 中，您可以通过在更具体的配置中指定一个否定的 glob 来取消排除路径

{
  "fmt": {
    "exclude": [
      // format the dist folder even though it's
      // excluded at the top level
      "!dist"
    ]
  },
  "exclude": [
    "dist/"
  ]
}

发布 - 覆盖 .gitignore 跳转到标题#

deno publish 命令会考虑 .gitignore 文件。在 Deno 1.41.2+ 中，您可以使用否定的排除 glob 来选择不忽略 .gitignore 中排除的文件

dist/
.env

{
  "publish": {
    "exclude": [
      // include the .gitignored dist folder
      "!dist/"
    ]
  }
}

或者，在 "include" 中明确指定被 git 忽略的路径也同样有效

{
  "publish": {
    "include": [
      "dist/",
      "README.md",
      "deno.json"
    ]
  }
}

deno.json 文件示例 跳转到标题#

{
  "compilerOptions": {
    "allowJs": true,
    "lib": ["deno.window"],
    "strict": true
  },
  "lint": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"],
    "rules": {
      "tags": ["recommended"],
      "include": ["ban-untagged-todo"],
      "exclude": ["no-unused-vars"]
    }
  },
  "fmt": {
    "useTabs": true,
    "lineWidth": 80,
    "indentWidth": 4,
    "semiColons": false,
    "singleQuote": true,
    "proseWrap": "preserve",
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  },
  "lock": false,
  "nodeModulesDir": "auto",
  "unstable": ["webgpu"],
  "test": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  },
  "tasks": {
    "start": "deno run --allow-read main.ts"
  },
  "imports": {
    "oak": "jsr:@oak/oak"
  },
  "exclude": [
    "dist/"
  ]
}

这是 deno.json 文件的一个示例，它配置了 TypeScript 编译器选项、代码检查器、格式化程序、node 模块目录等。有关所有可用字段和配置的完整列表，请参阅 Deno 配置文件模式。

JSON 模式 跳转到标题#

为方便编辑器提供自动补全功能，提供了 JSON 模式文件。该文件已版本化，可在此处获取：https://github.com/denoland/deno/blob/main/cli/schemas/config-file.v1.json

代理 跳转到标题#

Deno 支持模块下载和 fetch API 的代理。代理配置从环境变量中读取：HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。

如果您使用的是 Windows 系统——如果未找到环境变量，Deno 会回退到从注册表读取代理配置。