deno.json 和 package.json

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

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

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

package.json 支持 Jump to heading#

为了与 Node.js 项目兼容，Deno 也支持 package.json 文件。如果你有一个 Node.js 项目，则不必创建 deno.json 文件。Deno 将使用 package.json 文件来配置项目。

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

依赖项 Jump to heading#

deno.json 中的 "imports" 字段允许你指定项目中使用的依赖项。你可以使用它将裸标识符映射到 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。

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

自定义路径映射 Jump to heading#

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 或文件路径进行解析。

任务 Jump to heading#

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 的信息。

代码检查 Jump to heading#

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 进行代码检查 的信息。

格式化 Jump to heading#

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 格式化代码 的信息。

锁定文件 Jump to heading#

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

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

此配置将

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

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

{
  "lock": false
}

Node 模块目录 Jump to heading#

默认情况下，如果你的项目目录中有一个 package.json 文件，Deno 将使用本地 node_modules 目录。

你可以使用 deno.json 文件中的 nodeModulesDir 字段来控制此行为。

{
  "nodeModulesDir": "auto"
}

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

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

• "none" 如果你的项目目录中没有 package.json 文件
• "manual" 如果你的项目目录中有一个 package.json 文件

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

TypeScript 编译器选项 Jump to heading#

deno.json 文件中的 compilerOptions 字段用于为你的 Deno 项目配置 TypeScript 编译器设置。这允许你自定义 TypeScript 代码的编译方式，确保它与你的项目需求和编码标准保持一致。

另请参阅 在 Deno 中配置 TypeScript。

不稳定特性 Jump to heading#

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

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

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

了解更多.

包含和排除 Jump to heading#

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

包含 Jump to heading#

只有此处指定的路径或模式才会被包含。

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

排除 Jump to heading#

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

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

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

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

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

顶层排除 Jump to heading#

如果有一个目录是你永远不想让 Deno 进行格式化、代码检查、类型检查、在 LSP 中分析等操作的，那么请将其在顶层排除数组中指定

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

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

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

发布 - 覆盖 .gitignore Jump to heading#

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

dist/
.env

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

或者，在 "include" 中显式指定 gitignore 的路径也有效

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

完整示例 Jump to heading#

{
  "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/"
  ]
}

JSON 模式 Jump to heading#

JSON 模式文件可用于编辑器以提供自动完成功能。该文件已版本化，可在以下位置获得：https://deno.land/x/deno/cli/schemas/config-file.v1.json

代理 Jump to heading#

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

如果你使用的是 Windows - 如果找不到环境变量，Deno 将回退到从注册表读取代理。