Skip to main content
On this page

配置文件（deno.json）

View Page as MarkdownOpen the Markdown file in a new tabOpen in ClaudeAsk Claude about this pagellms.txtMachine-readable index of these docs for AI tools

本页文档介绍你可以在 deno.json（或 deno.jsonc）配置文件中设置的字段。有关 Deno 如何发现并应用配置，以及 deno.json 与 package.json 的关系概览，请参阅 配置 概念页面。

依赖 Jump to heading

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

例如，如果你想在项目中使用标准库中的 assert 模块，你可以使用这个 import map：

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

然后你的脚本就可以使用裸 specifier @std/assert：

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

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

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

package.json
{
  "dependencies": {
    "express": "^1.0.0"
  }
}
script.ts
import express from "express";

const app = express();

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

了解更多关于 模块导入和依赖 的内容

自定义路径映射 Jump to heading

deno.json 中的 import map 可用于更通用地映射 specifier 的路径。你可以将某个精确的 specifier 映射到第三方模块或直接映射到一个文件，也可以将导入 specifier 的一部分映射到某个目录。

deno.jsonc
{
  "imports": {
    // 映射到一个精确文件
    "foo": "./some/long/path/foo.ts",
    // 映射到一个目录，使用方式："bar/file.ts"
    "bar/": "./some/folder/bar/"
  }
}

用法：

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

导入 specifier 的路径映射通常用于较大的代码库，以简化书写。

例如：

deno.json
{
  "imports": {
    "@/": "./"
  }
}
main.ts
import { MyUtil } from "@/util.ts";

这会使以 @/ 开头的导入 specifier 相对于 import map 的 URL 或文件路径进行解析。

覆盖包 Jump to heading

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

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

此功能解决了若干常见的开发难题：

  • 依赖漏洞修复
  • 私有本地库
  • 兼容性问题

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

任务 Jump to heading

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

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

deno.json
{
  "tasks": {
    "start": "deno run --allow-net --watch=static/,routes/,data/ dev.ts",
    "test": "deno test --allow-net",
    "lint": "deno lint"
  }
}
package.json
{
  "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 内置代码检查器的行为。这使你可以指定要包含或排除在代码检查之外的文件，并自定义代码检查规则以满足项目需求。

例如：

deno.json
{
  "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 内置代码格式化器的行为。这使你可以自定义代码的格式化方式，确保整个项目的一致性，从而更易于阅读和协作。以下是你可以配置的关键选项：

deno.json
{
  "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 文件。

fmt 字段接受以下选项，每项都显示其默认值和允许值：

选项 默认值 可选值
bracePosition sameLine maintain, sameLine, nextLine, sameLineUnlessHanging
indentWidth 2 一个数字
lineWidth 80 一个数字
newLineKind lf auto, crlf, lf, system
nextControlFlowPosition sameLine sameLine, nextLine, maintain
operatorPosition sameLine sameLine, nextLine, maintain
proseWrap always always, never, preserve
quoteProps asNeeded asNeeded, consistent, preserve
semiColons true true, false
singleBodyPosition sameLineUnlessHanging sameLine, nextLine, maintain, sameLineUnlessHanging
singleQuote false true, false
spaceAround false true, false
spaceSurroundingProperties true true, false
trailingCommas always always, never
typeLiteral.separatorKind semiColon comma, semiColon
useBraces whenNotSingleLine maintain, whenNotSingleLine, always, preferNone
useTabs false true, false
jsx.bracketPosition nextLine maintain, sameLine, nextLine
jsx.forceNewLinesSurroundingContent false true, false
jsx.multiLineParens prefer never, prefer, always
unstable-component false true, false
unstable-sql false true, false

了解更多关于 使用 Deno 格式化代码 的内容。

Lockfile Jump to heading

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

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

此配置将：

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

Deno 默认使用锁文件，你可以使用以下配置将其禁用：

deno.json
{
  "lock": false
}

最小依赖年龄 Jump to heading

minimumDependencyAge 字段会阻止 Deno 安装发布时间晚于所配置时长的 npm 或 JSR 包版本。刚发布的恶意版本通常会在几天内被检测并撤下，因此设置一个较小的延迟窗口可以捕获大部分供应链攻击。关于如何选择窗口，请参阅 供应链管理。

deno.json
{
  // 不要安装发布时间不足 3 天的版本
  "minimumDependencyAge": "P3D"
}

该值可接受 ISO-8601 持续时间，例如 P3D 或 PT72H，也可以是分钟数（120）、绝对截止日期（2025-09-16）或 RFC3339 时间戳，或者使用 0 来禁用。

如需排除特定包，请使用带有 exclude 列表的对象形式：

deno.json
{
  "minimumDependencyAge": {
    "age": "P3D",
    "exclude": ["npm:@mycompany/cli", "jsr:@mycompany/lib"]
  }
}

同样的控制也可以通过 --minimum-dependency-age CLI 标志以及在 .npmrc 中使用 min-release-age 来实现。

Node 模块目录 Jump to heading

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

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

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

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

值 行为
"none" 不使用本地 node_modules 目录。改为使用 $DENO_DIR 中由 Deno 自动保持最新的全局缓存。
"auto" 使用本地 node_modules 目录。该目录会由 Deno 自动创建并保持最新。
"manual" 使用本地 node_modules 目录。用户必须手动保持该目录为最新，例如使用 deno install 或 npm install。

无需显式指定此设置，会应用以下默认值：

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

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

TypeScript 编译器选项 Jump to heading

deno.json 文件中的 compilerOptions 字段用于为你的 Deno 项目配置 TypeScript 编译器设置。这使你可以自定义 TypeScript 代码的编译方式，确保其符合你的项目需求和编码规范。

Info

Deno 推荐使用默认的 TypeScript 配置。这在共享代码时会有帮助。

如果你正在从 Node.js 迁移，你现有的 tsconfig.json 文件可以直接与 Deno 一起使用。有关支持的字段和优先级规则，请参阅 tsconfig.json 兼容性参考。

关于受支持的编译器选项、库配置和高级设置的完整列表，请参阅 配置 TypeScript。

不稳定特性 Jump to heading

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

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

deno.json
{
  "unstable": ["cron", "kv", "webgpu"]
}

了解更多。

include 和 exclude Jump to heading

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

include Jump to heading

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

{
  "lint": {
    // 仅格式化 src/ 目录
    "include": ["src/"]
  }
}

exclude Jump to heading

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

{
  "lint": {
    // 不对 dist/ 文件夹进行 lint
    "exclude": ["dist/"]
  }
}

它的优先级高于 include；如果某个路径同时匹配 include 和 exclude，则会以 exclude 为准。

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

{
  "fmt": {
    // 不格式化 "fixtures" 目录，
    // 但格式化 "fixtures/scripts"
    "exclude": [
      "fixtures",
      "!fixtures/scripts"
    ]
  }
}

顶层 exclude Jump to heading

如果有某个目录你绝不希望 Deno 对其进行 fmt、lint、类型检查、在 LSP 中分析等，那么请在顶层 exclude 数组中指定它：

{
  "exclude": [
    // 从所有子命令和 LSP 中排除 dist 文件夹
    "dist/"
  ]
}

有时你可能希望取消排除某个在顶层 exclude 中被排除的路径或模式。在 Deno 1.41.2+ 中，你可以在更具体的配置中指定一个取反的 glob 来取消排除某个路径：

{
  "fmt": {
    "exclude": [
      // 即使 dist 文件夹在顶层被排除，
      // 也要格式化它
      "!dist"
    ]
  },
  "exclude": [
    "dist/"
  ]
}

发布 - 覆盖 .gitignore Jump to heading

deno publish 命令会考虑 .gitignore。在 Deno 1.41.2+ 中，你可以通过使用取反的 exclude glob 来选择不忽略 .gitignore 中被忽略的文件：

.gitignore
dist/
.env
deno.json
{
  "publish": {
    "exclude": [
      // 包含被 .gitignore 忽略的 dist 文件夹
      "!dist/"
    ]
  }
}

另外，也可以在 "include" 中显式指定被 gitignore 的路径：

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

导出 Jump to heading

deno.json 文件中的 exports 字段允许你定义包中的哪些路径应可公开访问。这对于控制包的 API 暴露面并确保只有预期的代码部分对用户可见尤其有用。

deno.json
{
  "exports": "./src/mod.ts" // 默认入口点
}

你也可以定义多个入口点：

deno.json
{
  "exports": {
    "./module1": "./src/module1.ts",
    "./module2": "./src/module2.ts",
    ".": "./src/mod.ts" // 默认入口点
  }
}

此配置将会：

  • 将 module1 和 module2 作为你的包的入口点暴露出来，并且
  • 将 ./src/mod.ts 设为默认入口点（.）。

用户可以使用指定的路径导入这些模块，而你包中的其他文件仍保持私有。

要在代码中使用这些导出，你可以这样导入：

example.ts
import * as module_1 from "@example/my-package/module1";
import * as module_2 from "@example/my-package/module2";

权限 Jump to heading

Deno 2.5+ 支持在配置文件中存储 权限 集。

命名权限 Jump to heading

权限可以在 "permissions" 键下，以任意命名的权限集中的键值对形式定义。对于每个权限集：

  • 键是一个 权限 的名称，在 CLI 调用中它会跟在 --allow- 或 --deny- 后面（即 read、write、net、env、sys、run、ffi、import）
  • 值可以是布尔值（true / false 分别对应允许 / 拒绝）、表示路径、域名等的字符串数组，或包含 allow、deny 和/或 ignore 布尔键值对的对象。
{
  "permissions": {
    "read-data": {
      "read": "./data"
    },
    "read-and-write": {
      "read": true,
      "write": ["./data"]
    }
  }
}

可以通过指定 --permission-set=<name> 或 -P=<name> 标志来使用权限集：

>_
$ deno run -P=read-data main.ts

默认权限 Jump to heading

特殊的 "default" 权限键允许在使用 --permission-set/-P 标志时省略名称：

{
  "permissions": {
    "default": {
      "env": true
    }
  }
}

然后只需使用 -P 运行：

>_
$ deno run -P main.ts

allow、deny 和 ignore Jump to heading

为了对权限进行更精细的控制，你可以使用带有 allow、deny 和 ignore 键的对象形式。当你需要比简单的布尔值或数组值提供的更细粒度的权限控制时，这一点尤其有用。

对象形式语法 Jump to heading

而不是将权限指定为布尔值或数组：

{
  "permissions": {
    "default": {
      "read": true, // 简单布尔形式
      "write": ["./data"] // 简单数组形式
    }
  }
}

你可以使用对象形式：

{
  "permissions": {
    "default": {
      "read": {
        "allow": ["./data", "./config"],
        "deny": ["./data/secrets"],
        "ignore": ["./data/cache"]
      },
      "write": {
        "allow": ["./output"],
        "deny": ["./output/system"]
      }
    }
  }
}

可用权限 Jump to heading

allow、deny 和 ignore 键的工作方式会因权限类型而异：

  • read 和 env：支持 allow、deny 和 ignore
  • write、net、run、ffi、sys 和 import：支持 allow 和 deny（不支持 ignore）

行为 Jump to heading

  • allow：显式授予对特定资源的访问权限。可以是 true（允许全部）、false（不允许任何）、或者允许的特定路径/值数组。
  • deny：显式拒绝访问特定资源（抛出 PermissionDenied），即使这些资源在其他情况下本应被允许。可以是 true（拒绝全部）、false（拒绝任何）、或者拒绝的特定路径/值数组。
  • ignore：（仅适用于 read 和 env 权限）静默忽略对特定资源的访问尝试，而不抛出错误。可以是 true、false，或者要忽略的特定路径/值数组。

示例 Jump to heading

{
  "permissions": {
    "default": {
      // 允许从 data 目录读取，但拒绝访问 secrets，
      // 并静默忽略 cache 文件
      "read": {
        "allow": ["./data"],
        "deny": ["./data/secrets"],
        "ignore": ["./data/cache"]
      },
      // 允许所有环境变量，除了 API 密钥
      "env": {
        "allow": true,
        "ignore": ["API_KEY", "SECRET_TOKEN"]
      },
      // 允许全部，但拒绝 'rm'、'sudo'
      "run": {
        "allow": true,
        "deny": ["rm", "sudo"]
      }
    }
  }
}

测试、基准测试和编译权限 Jump to heading

可以在 "test"、"bench" 或 "compile" 键内可选地指定权限。

{
  "test": {
    "permissions": {
      "read": ["./data"]
    }
  }
}

或者引用一个权限集：

{
  "test": {
    "permissions": "read-data"
  },
  "permissions": {
    "read-data": {
      "read": ["./data"]
    }
  }
}

定义后，你必须使用 -P 或权限标志运行 deno test：

> deno test
error: 在配置文件中发现了测试权限。你是想使用 `-P` 运行吗？
    at file:///Users/david/dev/example/deno.json
> deno test -P
...运行...
> deno test --allow-read
...运行...
> deno test -A
...运行...

这样做是为了帮助你避免在忘记以权限方式运行时，还要花时间困惑为什么某些东西不起作用。

请注意，工作区中的 test 和 bench 文件会使用最近的 deno.json 来确定 test 和 bench 权限。这允许为不同的工作区成员分配不同的权限。

安全风险 Jump to heading

配置文件中权限的威胁模型与 deno task 类似，因为脚本可能会修改 deno.json 以提升权限。这就是为什么它需要通过 -P 显式启用，并且默认不会加载。

如果你可以接受这种风险，那么这个特性会对你很有用。

编译配置 Jump to heading

"compile" 块用于配置 deno compile，无需你在每次调用时重复传递标志。你可以声明要打包进可执行文件的额外文件或目录，以及要排除的路径：

deno.json
{
  "compile": {
    "include": ["names.csv", "data", "worker.ts"],
    "exclude": ["data/secrets", "**/*.test.ts"]
  }
}

命令行中的 --include 和 --exclude 标志会与这些列表合并，而不是替换它们。"compile" 块还可以携带 permissions（参见 测试、基准测试和编译权限）。

一个 deno.json 文件示例 Jump to heading

{
  "compilerOptions": {
    "allowJs": true,
    "lib": ["deno.window"],
    "strict": true
  },
  "permissions": {
    "default": {
      "read": {
        "allow": ["./src/"],
        "deny": ["./src/secrets/"]
      },
      "env": {
        "allow": true,
        "ignore": ["TEMP_*"]
      }
    }
  },
  "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/"
  ]
}

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

JSON 模式 Jump to heading

编辑器可使用一个 JSON 模式文件来提供自动补全。该文件有版本管理，并可在以下地址获取： https://github.com/denoland/deno/blob/main/cli/schemas/config-file.v1.json

代理 Jump to heading

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

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

Last updated on

Did you find what you needed?

编辑此页面
Privacy policy